gst/gstelement.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstelement.c: The base element, all elements derive from this
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 /* #define GST_DEBUG_ENABLED */
  24 #include <glib.h>
  25 #include <stdarg.h>
  26 #include "gst_private.h"
  27
  28 #include "gstelement.h"
  29 #include "gstextratypes.h"
  30 #include "gstbin.h"
  31 #include "gstscheduler.h"
  32 #include "gstevent.h"
  33 #include "gstutils.h"
  34
  35 /* Element signals and args */
  36 enum {
  37   STATE_CHANGE,
  38   NEW_PAD,
  39   PAD_REMOVED,
  40   ERROR,
  41   EOS,
  42   LAST_SIGNAL
  43 };
  44
  45 enum {
  46   ARG_0,
  47   /* FILL ME */
  48 };
  49
  50 #define CLASS(element)  GST_ELEMENT_CLASS (G_OBJECT_GET_CLASS (element))
  51
  52 static void                     gst_element_class_init          (GstElementClass *klass);
  53 static void                     gst_element_init                (GstElement *element);
  54 static void                     gst_element_base_class_init     (GstElementClass *klass);
  55
  56 static void                     gst_element_set_property        (GObject *object, guint prop_id,
  57                                                                  const GValue *value, GParamSpec *pspec);
  58 static void                     gst_element_get_property        (GObject *object, guint prop_id, GValue *value,
  59                                                                  GParamSpec *pspec);
  60
  61 static void                     gst_element_dispose             (GObject *object);
  62
  63 static GstElementStateReturn    gst_element_change_state        (GstElement *element);
  64 static void                     gst_element_error_func          (GstElement* element, GstElement *source, gchar *errormsg);
  65
  66 #ifndef GST_DISABLE_LOADSAVE
  67 static xmlNodePtr               gst_element_save_thyself        (GstObject *object, xmlNodePtr parent);
  68 static void                     gst_element_restore_thyself     (GstObject *parent, xmlNodePtr self);
  69 #endif
  70
  71 GType _gst_element_type = 0;
  72
  73 static GstObjectClass *parent_class = NULL;
  74 static guint gst_element_signals[LAST_SIGNAL] = { 0 };
  75
  76 GType gst_element_get_type (void)
  77 {
  78   if (!_gst_element_type) {
  79     static const GTypeInfo element_info = {
  80       sizeof(GstElementClass),
  81       (GBaseInitFunc)gst_element_base_class_init,
  82       NULL,
  83       (GClassInitFunc)gst_element_class_init,
  84       NULL,
  85       NULL,
  86       sizeof(GstElement),
  87       0,
  88       (GInstanceInitFunc)gst_element_init,
  89       NULL
  90     };
  91     _gst_element_type = g_type_register_static(GST_TYPE_OBJECT, "GstElement", &element_info, G_TYPE_FLAG_ABSTRACT);
  92   }
  93   return _gst_element_type;
  94 }
  95
  96 static void
  97 gst_element_class_init (GstElementClass *klass)
  98 {
  99   GObjectClass *gobject_class;
 100   GstObjectClass *gstobject_class;
 101
 102   gobject_class = (GObjectClass*) klass;
 103   gstobject_class = (GstObjectClass*) klass;
 104
 105   parent_class = g_type_class_ref(GST_TYPE_OBJECT);
 106
 107   gst_element_signals[STATE_CHANGE] =
 108     g_signal_new ("state_change", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 109                   G_STRUCT_OFFSET (GstElementClass, state_change), NULL, NULL,
 110                   gst_marshal_VOID__INT_INT, G_TYPE_NONE, 2,
 111                   G_TYPE_INT, G_TYPE_INT);
 112   gst_element_signals[NEW_PAD] =
 113     g_signal_new ("new_pad", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 114                   G_STRUCT_OFFSET (GstElementClass, new_pad), NULL, NULL,
 115                   gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1,
 116                   G_TYPE_OBJECT);
 117   gst_element_signals[PAD_REMOVED] =
 118     g_signal_new ("pad_removed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 119                   G_STRUCT_OFFSET (GstElementClass, pad_removed), NULL, NULL,
 120                   gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1,
 121                   G_TYPE_OBJECT);
 122   gst_element_signals[ERROR] =
 123     g_signal_new ("error", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 124                   G_STRUCT_OFFSET (GstElementClass, error), NULL, NULL,
 125                   gst_marshal_VOID__OBJECT_STRING, G_TYPE_NONE, 2,
 126                   G_TYPE_OBJECT, G_TYPE_STRING);
 127   gst_element_signals[EOS] =
 128     g_signal_new ("eos", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 129                   G_STRUCT_OFFSET (GstElementClass,eos), NULL, NULL,
 130                   gst_marshal_VOID__VOID, G_TYPE_NONE, 0);
 131
 132
 133
 134   gobject_class->set_property           = GST_DEBUG_FUNCPTR (gst_element_set_property);
 135   gobject_class->get_property           = GST_DEBUG_FUNCPTR (gst_element_get_property);
 136   gobject_class->dispose                = GST_DEBUG_FUNCPTR (gst_element_dispose);
 137
 138 #ifndef GST_DISABLE_LOADSAVE
 139   gstobject_class->save_thyself         = GST_DEBUG_FUNCPTR (gst_element_save_thyself);
 140   gstobject_class->restore_thyself      = GST_DEBUG_FUNCPTR (gst_element_restore_thyself);
 141 #endif
 142
 143   klass->change_state                   = GST_DEBUG_FUNCPTR (gst_element_change_state);
 144   klass->error                          = GST_DEBUG_FUNCPTR (gst_element_error_func);
 145   klass->elementfactory                 = NULL;
 146   klass->padtemplates                   = NULL;
 147   klass->numpadtemplates                = 0;
 148 }
 149
 150 static void
 151 gst_element_base_class_init (GstElementClass *klass)
 152 {
 153   GObjectClass *gobject_class;
 154
 155   gobject_class = (GObjectClass*) klass;
 156
 157   gobject_class->set_property =         GST_DEBUG_FUNCPTR(gst_element_set_property);
 158   gobject_class->get_property =         GST_DEBUG_FUNCPTR(gst_element_get_property);
 159 }
 160
 161 static void
 162 gst_element_init (GstElement *element)
 163 {
 164   element->current_state = GST_STATE_NULL;
 165   element->pending_state = GST_STATE_VOID_PENDING;
 166   element->numpads = 0;
 167   element->numsrcpads = 0;
 168   element->numsinkpads = 0;
 169   element->pads = NULL;
 170   element->loopfunc = NULL;
 171   element->sched = NULL;
 172   element->sched_private = NULL;
 173   element->state_mutex = g_mutex_new ();
 174   element->state_cond = g_cond_new ();
 175 }
 176
 177
 178 static void
 179 gst_element_set_property (GObject *object, guint prop_id, const GValue *value, GParamSpec *pspec)
 180 {
 181   GstElementClass *oclass = CLASS (object);
 182
 183   if (oclass->set_property)
 184     (oclass->set_property) (object, prop_id, value, pspec);
 185 }
 186
 187
 188 static void
 189 gst_element_get_property (GObject *object, guint prop_id, GValue *value, GParamSpec *pspec)
 190 {
 191   GstElementClass *oclass = CLASS (object);
 192
 193   if (oclass->get_property)
 194     (oclass->get_property) (object, prop_id, value, pspec);
 195 }
 196
 197
 198 /**
 199  * gst_element_set_name:
 200  * @element: GstElement to set name of
 201  * @name: new name of element
 202  *
 203  * Set the name of the element, getting rid of the old name if there was
 204  * one.
 205  */
 206 void
 207 gst_element_set_name (GstElement *element, const gchar *name)
 208 {
 209   g_return_if_fail (element != NULL);
 210   g_return_if_fail (GST_IS_ELEMENT (element));
 211
 212   gst_object_set_name (GST_OBJECT (element), name);
 213 }
 214
 215 /**
 216  * gst_element_get_name:
 217  * @element: GstElement to get name of
 218  *
 219  * Get the name of the element.
 220  *
 221  * Returns: name of the element
 222  */
 223 const gchar*
 224 gst_element_get_name (GstElement *element)
 225 {
 226   g_return_val_if_fail (element != NULL, NULL);
 227   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 228
 229   return GST_OBJECT_NAME (element);
 230 }
 231
 232 /**
 233  * gst_element_set_parent:
 234  * @element: GstElement to set parent of
 235  * @parent: new parent of the object
 236  *
 237  * Set the parent of the element.
 238  */
 239 void
 240 gst_element_set_parent (GstElement *element, GstObject *parent)
 241 {
 242   g_return_if_fail (element != NULL);
 243   g_return_if_fail (GST_IS_ELEMENT (element));
 244   g_return_if_fail (GST_OBJECT_PARENT (element) == NULL);
 245   g_return_if_fail (parent != NULL);
 246   g_return_if_fail (GST_IS_OBJECT (parent));
 247   g_return_if_fail ((gpointer)element != (gpointer)parent);
 248
 249   gst_object_set_parent (GST_OBJECT (element), parent);
 250 }
 251
 252 /**
 253  * gst_element_get_parent:
 254  * @element: GstElement to get the parent of
 255  *
 256  * Get the parent of the element.
 257  *
 258  * Returns: parent of the element
 259  */
 260 GstObject*
 261 gst_element_get_parent (GstElement *element)
 262 {
 263   g_return_val_if_fail (element != NULL, NULL);
 264   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 265
 266   return GST_OBJECT_PARENT (element);
 267 }
 268
 269 /**
 270  * gst_element_set_clock:
 271  * @element: GstElement to set the clock to
 272  * @clock: the clock to set for the element
 273  *
 274  * Set the clock for the element
 275  */
 276 void
 277 gst_element_set_clock (GstElement *element, GstClock *clock)
 278 {
 279   g_return_if_fail (element != NULL);
 280   g_return_if_fail (GST_IS_ELEMENT (element));
 281
 282   if (element->setclockfunc)
 283     element->setclockfunc (element, clock);
 284 }
 285
 286 /**
 287  * gst_element_get_clock:
 288  * @element: GstElement to get the clock of
 289  *
 290  * Get the clock of the element
 291  *
 292  * Returns: the clock of the element.
 293  */
 294 GstClock*
 295 gst_element_get_clock (GstElement *element)
 296 {
 297   g_return_val_if_fail (element != NULL, NULL);
 298   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 299
 300   if (element->getclockfunc)
 301     return element->getclockfunc (element);
 302
 303   return NULL;
 304 }
 305
 306 /**
 307  * gst_element_clock_wait:
 308  * @element: GstElement to wait for the clock
 309  * @clock: the clock to wait for
 310  * @time: the time to wait for
 311  *
 312  * Wait for a specific time on the clock
 313  *
 314  * Returns: the result of the wait operation
 315  */
 316 GstClockReturn
 317 gst_element_clock_wait (GstElement *element, GstClock *clock, GstClockTime time)
 318 {
 319   g_return_val_if_fail (element != NULL, GST_CLOCK_ERROR);
 320   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_CLOCK_ERROR);
 321
 322   if (GST_ELEMENT_SCHED (element)) {
 323     return gst_scheduler_clock_wait (GST_ELEMENT_SCHED (element), element, clock, time);
 324   }
 325   else
 326     return GST_CLOCK_TIMEOUT;
 327 }
 328
 329 /**
 330  * gst_element_add_pad:
 331  * @element: element to add pad to
 332  * @pad: pad to add
 333  *
 334  * Add a pad (connection point) to the element, setting the parent of the
 335  * pad to the element (and thus adding a reference).
 336  */
 337 void
 338 gst_element_add_pad (GstElement *element, GstPad *pad)
 339 {
 340   g_return_if_fail (element != NULL);
 341   g_return_if_fail (GST_IS_ELEMENT (element));
 342   g_return_if_fail (pad != NULL);
 343   g_return_if_fail (GST_IS_PAD (pad));
 344
 345   /* first check to make sure the pad's parent is already set */
 346   g_return_if_fail (GST_PAD_PARENT (pad) == NULL);
 347
 348   /* then check to see if there's already a pad by that name here */
 349   g_return_if_fail (gst_object_check_uniqueness (element->pads, GST_PAD_NAME(pad)) == TRUE);
 350
 351   /* set the pad's parent */
 352   GST_DEBUG (GST_CAT_ELEMENT_PADS,"setting parent of pad '%s' to '%s'",
 353         GST_PAD_NAME (pad), GST_ELEMENT_NAME (element));
 354   gst_object_set_parent (GST_OBJECT (pad), GST_OBJECT (element));
 355
 356   /* add it to the list */
 357   element->pads = g_list_append (element->pads, pad);
 358   element->numpads++;
 359   if (gst_pad_get_direction (pad) == GST_PAD_SRC)
 360     element->numsrcpads++;
 361   else
 362     element->numsinkpads++;
 363
 364   /* emit the NEW_PAD signal */
 365   g_signal_emit (G_OBJECT (element), gst_element_signals[NEW_PAD], 0, pad);
 366 }
 367
 368 /**
 369  * gst_element_remove_pad:
 370  * @element: element to remove pad from
 371  * @pad: pad to remove
 372  *
 373  * Remove a pad (connection point) from the element,
 374  */
 375 void
 376 gst_element_remove_pad (GstElement *element, GstPad *pad)
 377 {
 378   g_return_if_fail (element != NULL);
 379   g_return_if_fail (GST_IS_ELEMENT (element));
 380   g_return_if_fail (pad != NULL);
 381   g_return_if_fail (GST_IS_PAD (pad));
 382
 383   g_return_if_fail (GST_PAD_PARENT (pad) == element);
 384
 385   /* check to see if the pad is still connected */
 386   /* FIXME: what if someone calls _remove_pad instead of
 387     _remove_ghost_pad? */
 388   if (GST_IS_REAL_PAD (pad)) {
 389     g_return_if_fail (GST_RPAD_PEER (pad) == NULL);
 390   }
 391
 392   /* remove it from the list */
 393   element->pads = g_list_remove (element->pads, pad);
 394   element->numpads--;
 395   if (gst_pad_get_direction (pad) == GST_PAD_SRC)
 396     element->numsrcpads--;
 397   else
 398     element->numsinkpads--;
 399
 400   g_signal_emit (G_OBJECT (element), gst_element_signals[PAD_REMOVED], 0, pad);
 401
 402   gst_object_unparent (GST_OBJECT (pad));
 403 }
 404
 405 /**
 406  * gst_element_add_ghost_pad:
 407  * @element: element to add ghost pad to
 408  * @pad: pad from which the new ghost pad will be created
 409  * @name: name of the new ghost pad
 410  *
 411  * Create a ghost pad from the given pad, and add it to the list of pads
 412  * for this element.
 413  *
 414  * Returns: the added ghost pad or NULL, if no ghost pad was created.
 415  */
 416 GstPad *
 417 gst_element_add_ghost_pad (GstElement *element, GstPad *pad, gchar *name)
 418 {
 419   GstPad *ghostpad;
 420
 421   g_return_val_if_fail (element != NULL, NULL);
 422   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 423   g_return_val_if_fail (pad != NULL, NULL);
 424   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
 425
 426   /* then check to see if there's already a pad by that name here */
 427   g_return_val_if_fail (gst_object_check_uniqueness (element->pads, name) == TRUE, NULL);
 428
 429   GST_DEBUG(GST_CAT_ELEMENT_PADS,"creating new ghost pad called %s, from pad %s:%s",
 430             name,GST_DEBUG_PAD_NAME(pad));
 431   ghostpad = gst_ghost_pad_new (name, pad);
 432
 433   /* add it to the list */
 434   GST_DEBUG(GST_CAT_ELEMENT_PADS,"adding ghost pad %s to element %s",
 435             name, GST_ELEMENT_NAME (element));
 436   element->pads = g_list_append (element->pads, ghostpad);
 437   element->numpads++;
 438   /* set the parent of the ghostpad */
 439   gst_object_set_parent (GST_OBJECT (ghostpad), GST_OBJECT (element));
 440
 441   GST_DEBUG(GST_CAT_ELEMENT_PADS,"added ghostpad %s:%s",GST_DEBUG_PAD_NAME(ghostpad));
 442
 443   /* emit the NEW_GHOST_PAD signal */
 444   g_signal_emit (G_OBJECT (element), gst_element_signals[NEW_PAD], 0, ghostpad);
 445
 446   return ghostpad;
 447 }
 448
 449 /**
 450  * gst_element_remove_ghost_pad:
 451  * @element: element to remove the ghost pad from
 452  * @pad: ghost pad to remove
 453  *
 454  * removes a ghost pad from an element
 455  */
 456 void
 457 gst_element_remove_ghost_pad (GstElement *element, GstPad *pad)
 458 {
 459   g_return_if_fail (element != NULL);
 460   g_return_if_fail (GST_IS_ELEMENT (element));
 461   g_return_if_fail (pad != NULL);
 462   g_return_if_fail (GST_IS_GHOST_PAD (pad));
 463
 464   /* FIXME this is redundant?
 465    * wingo 10-july-2001: I don't think so, you have to actually remove the pad
 466    * from the element. gst_pad_remove_ghost_pad just removes the ghostpad from
 467    * the real pad's ghost pad list
 468    */
 469   gst_pad_remove_ghost_pad (GST_PAD (GST_PAD_REALIZE (pad)), pad);
 470   gst_element_remove_pad (element, pad);
 471 }
 472
 473
 474 /**
 475  * gst_element_get_pad:
 476  * @element: element to find pad of
 477  * @name: name of pad to retrieve
 478  *
 479  * Retrieve a pad from the element by name.
 480  *
 481  * Returns: requested pad if found, otherwise NULL.
 482  */
 483 GstPad*
 484 gst_element_get_pad (GstElement *element, const gchar *name)
 485 {
 486   GList *walk;
 487
 488   g_return_val_if_fail (element != NULL, NULL);
 489   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 490   g_return_val_if_fail (name != NULL, NULL);
 491
 492   /* if there aren't any pads, well, we're not likely to find one */
 493   if (!element->numpads)
 494     return NULL;
 495
 496   /* look through the list, matching by name */
 497   walk = element->pads;
 498   while (walk) {
 499     GstPad *pad;
 500
 501     pad = GST_PAD(walk->data);
 502     if (!strcmp (GST_PAD_NAME(pad), name)) {
 503       GST_INFO(GST_CAT_ELEMENT_PADS,"found pad %s:%s",GST_DEBUG_PAD_NAME(pad));
 504       return pad;
 505     }
 506     walk = g_list_next (walk);
 507   }
 508
 509   GST_INFO(GST_CAT_ELEMENT_PADS,"no such pad '%s' in element \"%s\"",name,GST_ELEMENT_NAME(element));
 510   return NULL;
 511 }
 512
 513 /**
 514  * gst_element_get_pad_list:
 515  * @element: element to get pads of
 516  *
 517  * Retrieve a list of the pads associated with the element.
 518  *
 519  * Returns: GList of pads
 520  */
 521 GList*
 522 gst_element_get_pad_list (GstElement *element)
 523 {
 524   g_return_val_if_fail (element != NULL, NULL);
 525   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 526
 527   /* return the list of pads */
 528   return element->pads;
 529 }
 530
 531 /**
 532  * gst_element_class_add_padtemplate:
 533  * @klass: element class to add padtemplate to
 534  * @templ: padtemplate to add
 535  *
 536  * Add a padtemplate to an element class. This is useful if you have derived a custom
 537  * bin and wish to provide an on-request pad at runtime. Plugin writers should use
 538  * gst_elementfactory_add_padtemplate instead.
 539  */
 540 void
 541 gst_element_class_add_padtemplate (GstElementClass *klass, GstPadTemplate *templ)
 542 {
 543   g_return_if_fail (klass != NULL);
 544   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
 545   g_return_if_fail (templ != NULL);
 546   g_return_if_fail (GST_IS_PADTEMPLATE (templ));
 547
 548   klass->padtemplates = g_list_append (klass->padtemplates, templ);
 549   klass->numpadtemplates++;
 550 }
 551
 552 /**
 553  * gst_element_get_padtemplate_list:
 554  * @element: element to get padtemplates of
 555  *
 556  * Retrieve a list of the padtemplates associated with the element.
 557  *
 558  * Returns: GList of padtemplates
 559  */
 560 GList*
 561 gst_element_get_padtemplate_list (GstElement *element)
 562 {
 563   g_return_val_if_fail (element != NULL, NULL);
 564   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 565
 566   return CLASS (element)->padtemplates;
 567 }
 568
 569 /**
 570  * gst_element_get_padtemplate_by_name:
 571  * @element: element to get padtemplate of
 572  * @name: the name of the padtemplate to get.
 573  *
 574  * Retrieve a padtemplate from this element with the
 575  * given name.
 576  *
 577  * Returns: the padtemplate with the given name
 578  */
 579 GstPadTemplate*
 580 gst_element_get_padtemplate_by_name (GstElement *element, const guchar *name)
 581 {
 582   GList *padlist;
 583
 584   g_return_val_if_fail (element != NULL, NULL);
 585   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 586   g_return_val_if_fail (name != NULL, NULL);
 587
 588   padlist = gst_element_get_padtemplate_list (element);
 589
 590   while (padlist) {
 591     GstPadTemplate *padtempl = (GstPadTemplate*) padlist->data;
 592
 593     if (!strcmp (padtempl->name_template, name))
 594       return padtempl;
 595
 596     padlist = g_list_next (padlist);
 597   }
 598
 599   return NULL;
 600 }
 601
 602 /**
 603  * gst_element_get_padtemplate_by_compatible:
 604  * @element: element to get padtemplate of
 605  * @templ: a template to find a compatible template for
 606  *
 607  * Generate a padtemplate for this element compatible with the given
 608  * template, ie able to link to it.
 609  *
 610  * Returns: the padtemplate
 611  */
 612 static GstPadTemplate*
 613 gst_element_get_padtemplate_by_compatible (GstElement *element, GstPadTemplate *compattempl)
 614 {
 615   GstPadTemplate *newtempl = NULL;
 616   GList *padlist;
 617
 618   GST_DEBUG(GST_CAT_ELEMENT_PADS,"gst_element_get_padtemplate_by_compatible()");
 619
 620   g_return_val_if_fail (element != NULL, NULL);
 621   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 622   g_return_val_if_fail (compattempl != NULL, NULL);
 623
 624   padlist = gst_element_get_padtemplate_list (element);
 625
 626   while (padlist) {
 627     GstPadTemplate *padtempl = (GstPadTemplate*) padlist->data;
 628     gboolean compat = FALSE;
 629
 630     /* Ignore name
 631      * Ignore presence
 632      * Check direction (must be opposite)
 633      * Check caps
 634      */
 635     GST_DEBUG(GST_CAT_CAPS,"checking direction and caps");
 636     if (padtempl->direction == GST_PAD_SRC &&
 637       compattempl->direction == GST_PAD_SINK) {
 638       GST_DEBUG(GST_CAT_CAPS,"compatible direction: found src pad template");
 639       compat = gst_caps_check_compatibility(GST_PADTEMPLATE_CAPS (padtempl),
 640                                             GST_PADTEMPLATE_CAPS (compattempl));
 641       GST_DEBUG(GST_CAT_CAPS,"caps are %scompatible", (compat?"":"not "));
 642     } else if (padtempl->direction == GST_PAD_SINK &&
 643                compattempl->direction == GST_PAD_SRC) {
 644       GST_DEBUG(GST_CAT_CAPS,"compatible direction: found sink pad template");
 645       compat = gst_caps_check_compatibility(GST_PADTEMPLATE_CAPS (compattempl),
 646                                             GST_PADTEMPLATE_CAPS (padtempl));
 647       GST_DEBUG(GST_CAT_CAPS,"caps are %scompatible", (compat?"":"not "));
 648     }
 649
 650     if (compat) {
 651       newtempl = padtempl;
 652       break;
 653     }
 654
 655     padlist = g_list_next (padlist);
 656   }
 657
 658   return newtempl;
 659 }
 660
 661 static GstPad*
 662 gst_element_request_pad (GstElement *element, GstPadTemplate *templ, const gchar* name)
 663 {
 664   GstPad *newpad = NULL;
 665   GstElementClass *oclass;
 666
 667   oclass = CLASS (element);
 668   if (oclass->request_new_pad)
 669     newpad = (oclass->request_new_pad)(element, templ, name);
 670
 671   return newpad;
 672 }
 673
 674 /**
 675  * gst_element_request_compatible_pad:
 676  * @element: element to request a new pad from
 677  * @templ: a pad template to which the new pad should be able to connect
 678  *
 679  * Request a new pad from the element. The template will
 680  * be used to decide what type of pad to create. This function
 681  * is typically used for elements with a padtemplate with presence
 682  * GST_PAD_REQUEST.
 683  *
 684  * Returns: the new pad that was created.
 685  */
 686 GstPad*
 687 gst_element_request_compatible_pad (GstElement *element, GstPadTemplate *templ)
 688 {
 689   GstPadTemplate *templ_new;
 690   GstPad *pad = NULL;
 691
 692   g_return_val_if_fail (element != NULL, NULL);
 693   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 694   g_return_val_if_fail (templ != NULL, NULL);
 695
 696   templ_new = gst_element_get_padtemplate_by_compatible (element, templ);
 697   if (templ_new != NULL)
 698       pad = gst_element_request_pad (element, templ_new, NULL);
 699
 700   return pad;
 701 }
 702
 703 /**
 704  * gst_element_request_pad_by_name:
 705  * @element: element to request a new pad from
 706  * @name: the name of the padtemplate to use.
 707  *
 708  * Request a new pad from the element. The name argument will
 709  * be used to decide what padtemplate to use. This function
 710  * is typically used for elements with a padtemplate with presence
 711  * GST_PAD_REQUEST.
 712  *
 713  * Returns: the new pad that was created.
 714  */
 715 GstPad*
 716 gst_element_request_pad_by_name (GstElement *element, const gchar *name)
 717 {
 718   GstPadTemplate *templ = NULL;
 719   GstPad *pad;
 720   const gchar *req_name = NULL;
 721   gboolean templ_found = FALSE;
 722   GList *list;
 723   gint n;
 724   const gchar *data;
 725   gchar *str, *endptr;
 726
 727   g_return_val_if_fail (element != NULL, NULL);
 728   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 729   g_return_val_if_fail (name != NULL, NULL);
 730
 731
 732   if (strstr (name, "%")) {
 733     templ = gst_element_get_padtemplate_by_name (element, name);
 734     req_name = NULL;
 735     if (templ)
 736       templ_found = TRUE;
 737   } else {
 738     list = gst_element_get_padtemplate_list(element);
 739     while (!templ_found && list) {
 740       templ = (GstPadTemplate*) list->data;
 741       if (templ->presence == GST_PAD_REQUEST) {
 742         /* we know that %s and %d are the only possibilities because of sanity
 743            checks in gst_padtemplate_new */
 744         if ((str = strchr (templ->name_template, '%')) &&
 745             strncmp (templ->name_template, name, str - templ->name_template) == 0 &&
 746             strlen (name) > str - templ->name_template) {
 747           data = name + (str - templ->name_template);
 748           if (*(str+1) == 'd') {
 749             /* it's an int */
 750             n = (gint) strtol (data, &endptr, 10);
 751             if (endptr == NULL) {
 752               templ_found = TRUE;
 753               req_name = name;
 754               break;
 755             }
 756           } else {
 757             /* it's a string */
 758             templ_found = TRUE;
 759             req_name = name;
 760             break;
 761           }
 762         }
 763       }
 764       list = list->next;
 765     }
 766   }
 767
 768   if (!templ_found)
 769       return NULL;
 770
 771   pad = gst_element_request_pad (element, templ, req_name);
 772
 773   return pad;
 774 }
 775
 776 /**
 777  * gst_element_get_compatible_pad_filtered:
 778  * @element: the element in which the pad should be found
 779  * @pad: the pad to find a compatible one for
 780  * @filtercaps: the caps to use as a filter
 781  *
 782  * Looks for an unconnected pad to which the given pad can connect to.
 783  * It is not guaranteed that connecting the pads will work, though
 784  * it should work in most cases.
 785  *
 786  * Returns: the pad to which a connection can be made
 787  */
 788 GstPad*
 789 gst_element_get_compatible_pad_filtered (GstElement *element, GstPad *pad, GstCaps *filtercaps)
 790 {
 791   GList *pads;
 792   GstPadTemplate *templ;
 793   GstCaps *templcaps;
 794   GstPad *foundpad = NULL;
 795
 796   /* checks */
 797   g_return_val_if_fail (element != NULL, NULL);
 798   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 799   g_return_val_if_fail (pad != NULL, NULL);
 800   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
 801
 802   /* let's use the real pad */
 803   pad = (GstPad *) GST_PAD_REALIZE (pad);
 804   g_return_val_if_fail (pad != NULL, NULL);
 805   g_return_val_if_fail (GST_RPAD_PEER (pad) == NULL, NULL);
 806
 807   /* try to get an existing unconnected pad */
 808   pads = gst_element_get_pad_list (element);
 809   while (pads) {
 810     GstPad *current = GST_PAD (pads->data);
 811     if ((GST_PAD_PEER (GST_PAD_REALIZE (current)) == NULL) &&
 812         gst_pad_can_connect_filtered (pad, current, filtercaps)) {
 813       return current;
 814     }
 815     pads = g_list_next (pads);
 816   }
 817
 818   /* try to create a new one */
 819   /* requesting is a little crazy, we need a template. Let's create one */
 820   if (filtercaps != NULL) {
 821     templcaps = gst_caps_intersect (filtercaps, (GstCaps *) GST_RPAD_CAPS (pad));
 822     if (templcaps == NULL)
 823       return NULL;
 824   } else {
 825     templcaps = gst_caps_copy (gst_pad_get_caps (pad));
 826   }
 827
 828   templ = gst_padtemplate_new ((gchar *) GST_PAD_NAME (pad), GST_RPAD_DIRECTION (pad),
 829                                GST_PAD_ALWAYS, templcaps, NULL);
 830   foundpad = gst_element_request_compatible_pad (element, templ);
 831   gst_object_unref (GST_OBJECT (templ)); /* this will take care of the caps too */
 832
 833   /* FIXME: this is broken, but it's in here so autoplugging elements that don't
 834      have caps on their source padtemplates (spider) can connect... */
 835   if (!foundpad && !filtercaps) {
 836     templ = gst_padtemplate_new ((gchar *) GST_PAD_NAME (pad), GST_RPAD_DIRECTION (pad),
 837                                  GST_PAD_ALWAYS, NULL, NULL);
 838     foundpad = gst_element_request_compatible_pad (element, templ);
 839     gst_object_unref (GST_OBJECT (templ));
 840   }
 841
 842   return foundpad;
 843 }
 844
 845 /**
 846  * gst_element_get_compatible_pad:
 847  * @element: the element in which the pad should be found
 848  * @pad: the pad to find a compatible one for
 849  *
 850  * Looks for an unconnected pad to which the given pad can connect to.
 851  * It is not guaranteed that connecting the pads will work, though
 852  * it should work in most cases.
 853  *
 854  * Returns: the pad to which a connection can be made
 855  */
 856 GstPad*
 857 gst_element_get_compatible_pad (GstElement *element, GstPad *pad)
 858 {
 859   return gst_element_get_compatible_pad_filtered (element, pad, NULL);
 860 }
 861
 862 /**
 863  * gst_element_connect_elements_filtered:
 864  * @src: the element containing source pad
 865  * @dest: the element containing destination pad
 866  * @filtercaps: the caps to use as filter
 867  *
 868  * Connect the source to the destination element using the filtercaps.
 869  * The connection must be from source to destination, the other
 870  * direction will not be tried.
 871  * The functions looks for existing pads that aren't connected yet.
 872  + It will use request pads if possible. But both pads will not be requested.
 873  * If multiple connections are possible, only one is established.
 874  *
 875  * Returns: TRUE if the elements could be connected.
 876  */
 877 gboolean
 878 gst_element_connect_elements_filtered (GstElement *src, GstElement *dest,
 879                                        GstCaps *filtercaps)
 880 {
 881   GList *srcpads, *destpads, *srctempls, *desttempls, *l;
 882   GstPad *srcpad, *destpad;
 883   GstPadTemplate *srctempl, *desttempl;
 884
 885   /* checks */
 886   g_return_val_if_fail (src != NULL, FALSE);
 887   g_return_val_if_fail (GST_IS_ELEMENT(src), FALSE);
 888   g_return_val_if_fail (dest != NULL, FALSE);
 889   g_return_val_if_fail (GST_IS_ELEMENT(dest), FALSE);
 890
 891   GST_DEBUG (GST_CAT_ELEMENT_PADS, "attempting to connect element %s to element %s", GST_ELEMENT_NAME (src), GST_ELEMENT_NAME (dest));
 892
 893   /* loop through the existing pads in the source */
 894   srcpads = gst_element_get_pad_list (src);
 895   destpads = gst_element_get_pad_list (dest);
 896
 897   if (srcpads || destpads) {
 898     while (srcpads) {
 899       srcpad = (GstPad *) GST_PAD_REALIZE (srcpads->data);
 900       if ((GST_RPAD_DIRECTION (srcpad) == GST_PAD_SRC) &&
 901           (GST_PAD_PEER (srcpad) == NULL)) {
 902         destpad = gst_element_get_compatible_pad_filtered (dest, srcpad, filtercaps);
 903         if (destpad && gst_pad_connect_filtered (srcpad, destpad, filtercaps)) {
 904           GST_DEBUG (GST_CAT_ELEMENT_PADS, "connected pad %s:%s to pad %s:%s", GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (destpad));
 905           return TRUE;
 906         }
 907       }
 908       srcpads = g_list_next (srcpads);
 909     }
 910
 911     /* loop through the existing pads in the destination */
 912     while (destpads) {
 913       destpad = (GstPad *) GST_PAD_REALIZE (destpads->data);
 914       if ((GST_RPAD_DIRECTION (destpad) == GST_PAD_SINK) &&
 915           (GST_PAD_PEER (destpad) == NULL)) {
 916         srcpad = gst_element_get_compatible_pad_filtered (src, destpad, filtercaps);
 917         if (srcpad && gst_pad_connect_filtered (srcpad, destpad, filtercaps)) {
 918           GST_DEBUG (GST_CAT_ELEMENT_PADS, "connected pad %s:%s to pad %s:%s", GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (destpad));
 919           return TRUE;
 920         }
 921       }
 922       destpads = g_list_next (destpads);
 923     }
 924   }
 925
 926   GST_DEBUG (GST_CAT_ELEMENT_PADS, "we might have request pads on both sides, checking...");
 927   srctempls = gst_element_get_padtemplate_list (src);
 928   desttempls = gst_element_get_padtemplate_list (dest);
 929
 930   if (srctempls && desttempls) {
 931     while (srctempls) {
 932       srctempl = (GstPadTemplate*) srctempls->data;
 933       if (srctempl->presence == GST_PAD_REQUEST) {
 934         for (l=desttempls; l; l=l->next) {
 935           desttempl = (GstPadTemplate*) desttempls->data;
 936           if (desttempl->presence == GST_PAD_REQUEST && desttempl->direction != srctempl->direction) {
 937             if (gst_caps_check_compatibility (gst_padtemplate_get_caps (srctempl),
 938                                               gst_padtemplate_get_caps (desttempl))) {
 939               srcpad = gst_element_request_pad_by_name (src, srctempl->name_template);
 940               destpad = gst_element_request_pad_by_name (dest, desttempl->name_template);
 941               if (gst_pad_connect_filtered (srcpad, destpad, filtercaps)) {
 942                 GST_DEBUG (GST_CAT_ELEMENT_PADS, "connected pad %s:%s to pad %s:%s",
 943                            GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (destpad));
 944                 return TRUE;
 945               }
 946               /* FIXME: we have extraneous request pads lying around */
 947             }
 948           }
 949         }
 950       }
 951       srctempls = srctempls->next;
 952     }
 953   }
 954
 955   GST_DEBUG (GST_CAT_ELEMENT_PADS, "no connection possible from %s to %s", GST_ELEMENT_NAME (src), GST_ELEMENT_NAME (dest));
 956   return FALSE;
 957 }
 958
 959 /**
 960  * gst_element_connect_elements_many:
 961  * @element_1: the first element in the connection chain
 962  * @element_2: the second element in the connection chain
 963  * @...: NULL-terminated list of elements to connect in order
 964  *
 965  * Chain together a series of elements. Uses #gst_element_connect_elements.
 966  *
 967  * Returns: TRUE on success, FALSE otherwise.
 968  */
 969 /* API FIXME: this should be called gst_element_connect_many, and connect_elements
 970  * should just be connect */
 971 gboolean
 972 gst_element_connect_elements_many (GstElement *element_1, GstElement *element_2, ...)
 973 {
 974   va_list args;
 975
 976   g_return_val_if_fail (element_1 != NULL && element_2 != NULL, FALSE);
 977   g_return_val_if_fail (GST_IS_ELEMENT (element_1) && GST_IS_ELEMENT (element_2), FALSE);
 978
 979   va_start (args, element_2);
 980
 981   while (element_2) {
 982     if (!gst_element_connect_elements (element_1, element_2))
 983       return FALSE;
 984
 985     element_1 = element_2;
 986     element_2 = va_arg (args, GstElement*);
 987   }
 988
 989   va_end (args);
 990
 991   return TRUE;
 992 }
 993
 994 /**
 995  * gst_element_connect_elements:
 996  * @src: element containing source pad
 997  * @dest: element containing destination pad
 998  *
 999  * Connect the source to the destination element.
1000  * The connection must be from source to destination, the other
1001  * direction will not be tried.
1002  * The functions looks for existing pads and request pads that aren't
1003  * connected yet. If multiple connections are possible, only one is
1004  * established.
1005  *
1006  * Returns: TRUE if the elements could be connected.
1007  */
1008 gboolean
1009 gst_element_connect_elements (GstElement *src, GstElement *dest)
1010 {
1011   return gst_element_connect_elements_filtered (src, dest, NULL);
1012 }
1013
1014 /**
1015  * gst_element_connect_filtered:
1016  * @src: element containing source pad
1017  * @srcpadname: name of pad in source element
1018  * @dest: element containing destination pad
1019  * @destpadname: name of pad in destination element
1020  * @filtercaps: the caps to use as a filter
1021  *
1022  * Connect the two named pads of the source and destination elements.
1023  * Side effect is that if one of the pads has no parent, it becomes a
1024  * child of the parent of the other element.  If they have different
1025  * parents, the connection fails.
1026  *
1027  * Returns: TRUE if the pads could be connected.
1028  */
1029 gboolean
1030 gst_element_connect_filtered (GstElement *src, const gchar *srcpadname,
1031                               GstElement *dest, const gchar *destpadname,
1032                               GstCaps *filtercaps)
1033 {
1034   GstPad *srcpad,*destpad;
1035
1036   g_return_val_if_fail (src != NULL, FALSE);
1037   g_return_val_if_fail (GST_IS_ELEMENT(src), FALSE);
1038   g_return_val_if_fail (srcpadname != NULL, FALSE);
1039   g_return_val_if_fail (dest != NULL, FALSE);
1040   g_return_val_if_fail (GST_IS_ELEMENT(dest), FALSE);
1041   g_return_val_if_fail (destpadname != NULL, FALSE);
1042
1043   /* obtain the pads requested */
1044   srcpad = gst_element_get_pad (src, srcpadname);
1045   if (srcpad == NULL) {
1046     GST_ERROR (src, "source element has no pad \"%s\"", srcpadname);
1047     return FALSE;
1048   }
1049   destpad = gst_element_get_pad (dest, destpadname);
1050   if (srcpad == NULL) {
1051     GST_ERROR (dest, "destination element has no pad \"%s\"", destpadname);
1052     return FALSE;
1053   }
1054
1055   /* we're satisified they can be connected, let's do it */
1056   return gst_pad_connect_filtered (srcpad, destpad, filtercaps);
1057 }
1058
1059 /**
1060  * gst_element_connect:
1061  * @src: element containing source pad
1062  * @srcpadname: name of pad in source element
1063  * @dest: element containing destination pad
1064  * @destpadname: name of pad in destination element
1065  *
1066  * Connect the two named pads of the source and destination elements.
1067  * Side effect is that if one of the pads has no parent, it becomes a
1068  * child of the parent of the other element.  If they have different
1069  * parents, the connection fails.
1070  *
1071  * Returns: TRUE if the pads could be connected.
1072  */
1073 gboolean
1074 gst_element_connect (GstElement *src, const gchar *srcpadname,
1075                      GstElement *dest, const gchar *destpadname)
1076 {
1077   return gst_element_connect_filtered (src, srcpadname, dest, destpadname, NULL);
1078 }
1079
1080 /**
1081  * gst_element_disconnect:
1082  * @src: element containing source pad
1083  * @srcpadname: name of pad in source element
1084  * @dest: element containing destination pad
1085  * @destpadname: name of pad in destination element
1086  *
1087  * Disconnect the two named pads of the source and destination elements.
1088  */
1089 void
1090 gst_element_disconnect (GstElement *src, const gchar *srcpadname,
1091                         GstElement *dest, const gchar *destpadname)
1092 {
1093   GstPad *srcpad,*destpad;
1094
1095   g_return_if_fail (src != NULL);
1096   g_return_if_fail (GST_IS_ELEMENT(src));
1097   g_return_if_fail (srcpadname != NULL);
1098   g_return_if_fail (dest != NULL);
1099   g_return_if_fail (GST_IS_ELEMENT(dest));
1100   g_return_if_fail (destpadname != NULL);
1101
1102   /* obtain the pads requested */
1103   srcpad = gst_element_get_pad (src, srcpadname);
1104   if (srcpad == NULL) {
1105     GST_ERROR(src,"source element has no pad \"%s\"",srcpadname);
1106     return;
1107   }
1108   destpad = gst_element_get_pad (dest, destpadname);
1109   if (srcpad == NULL) {
1110     GST_ERROR(dest,"destination element has no pad \"%s\"",destpadname);
1111     return;
1112   }
1113
1114   /* we're satisified they can be disconnected, let's do it */
1115   gst_pad_disconnect(srcpad,destpad);
1116 }
1117
1118 /**
1119  * gst_element_disconnect_elements:
1120  * @src: source element
1121  * @dest: sink element
1122  *
1123  * Disconnect all pads connecting the two elements in the direction src -> dest.
1124  */
1125 void
1126 gst_element_disconnect_elements (GstElement *src, GstElement *dest)
1127 {
1128   GList *srcpads;
1129   GstPad *pad;
1130
1131   g_return_if_fail (GST_IS_ELEMENT(src));
1132   g_return_if_fail (GST_IS_ELEMENT(dest));
1133
1134   srcpads = gst_element_get_pad_list (src);
1135
1136   while (srcpads) {
1137     pad = GST_PAD (srcpads->data);
1138
1139     if (GST_PAD_DIRECTION (pad) == GST_PAD_SRC)
1140       if (GST_OBJECT_PARENT (GST_PAD_PEER (pad)) == (GstObject*) dest)
1141         gst_pad_disconnect (pad, GST_PAD_PEER (pad));
1142
1143     srcpads = g_list_next (srcpads);
1144   }
1145 }
1146
1147 static void
1148 gst_element_error_func (GstElement* element, GstElement *source, gchar *errormsg)
1149 {
1150   /* tell the parent */
1151   if (GST_OBJECT_PARENT (element)) {
1152     GST_DEBUG (GST_CAT_EVENT, "forwarding error \"%s\" from %s to %s", errormsg,
1153                GST_ELEMENT_NAME (element), GST_OBJECT_NAME (GST_OBJECT_PARENT (element)));
1154
1155     gst_object_ref (GST_OBJECT (element));
1156     g_signal_emit (G_OBJECT (GST_OBJECT_PARENT (element)), gst_element_signals[ERROR], 0, source, errormsg);
1157     gst_object_unref (GST_OBJECT (element));
1158   }
1159 }
1160 /**
1161  * gst_element_error:
1162  * @element: Element with the error
1163  * @error: A printf-like string describing the error
1164  * @...: optional arguments for the string
1165  *
1166  * This function is used internally by elements to signal an error
1167  * condition.  It results in the "error" signal.
1168  */
1169 void
1170 gst_element_error (GstElement *element, const gchar *error, ...)
1171 {
1172   va_list var_args;
1173   gchar *string;
1174
1175   /* checks */
1176   g_return_if_fail (GST_IS_ELEMENT (element));
1177   g_return_if_fail (element != NULL);
1178   g_return_if_fail (error != NULL);
1179
1180   /* create error message */
1181   va_start (var_args, error);
1182   string = g_strdup_vprintf (error, var_args);
1183   va_end (var_args);
1184   GST_INFO (GST_CAT_EVENT, "ERROR in %s: %s", GST_ELEMENT_NAME (element), string);
1185
1186   /* emit the signal, make sure the element stays available */
1187   gst_object_ref (GST_OBJECT (element));
1188   g_signal_emit (G_OBJECT (element), gst_element_signals[ERROR], 0, element, string);
1189
1190  /* tell the scheduler */
1191   if (element->sched) {
1192     gst_scheduler_error (element->sched, element);
1193   }
1194
1195   /* cleanup */
1196   gst_object_unref (GST_OBJECT (element));
1197   g_free (string);
1198 }
1199
1200 /**
1201  * gst_element_get_state:
1202  * @element: element to get state of
1203  *
1204  * Gets the state of the element.
1205  *
1206  * Returns: The element state
1207  */
1208 GstElementState
1209 gst_element_get_state (GstElement *element)
1210 {
1211   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_VOID_PENDING);
1212
1213   return GST_STATE (element);
1214 }
1215
1216 /**
1217  * gst_element_wait_state_change:
1218  * @element: element wait for
1219  *
1220  * Wait and block until the element changed its state.
1221  */
1222 void
1223 gst_element_wait_state_change (GstElement *element)
1224 {
1225   g_mutex_lock (element->state_mutex);
1226   g_cond_wait (element->state_cond, element->state_mutex);
1227   g_mutex_unlock (element->state_mutex);
1228 }
1229 /**
1230  * gst_element_set_state:
1231  * @element: element to change state of
1232  * @state: new element state
1233  *
1234  * Sets the state of the element. This function will only set
1235  * the elements pending state.
1236  *
1237  * Returns: whether or not the state was successfully set.
1238  */
1239 gint
1240 gst_element_set_state (GstElement *element, GstElementState state)
1241 {
1242   GstElementClass *oclass;
1243   GstElementState curpending;
1244   GstElementStateReturn return_val = GST_STATE_SUCCESS;
1245
1246   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_FAILURE);
1247
1248   /* start with the current state */
1249   curpending = GST_STATE(element);
1250
1251   GST_DEBUG_ELEMENT (GST_CAT_STATES, element, "setting state from %s to %s\n",
1252                      gst_element_statename (curpending),
1253                      gst_element_statename (state));
1254
1255   /* loop until the final requested state is set */
1256   while (GST_STATE (element) != state && GST_STATE (element) != GST_STATE_VOID_PENDING) {
1257     /* move the curpending state in the correct direction */
1258     if (curpending < state)
1259       curpending<<=1;
1260     else
1261       curpending>>=1;
1262
1263     /* set the pending state variable */
1264     /* FIXME: should probably check to see that we don't already have one */
1265     GST_STATE_PENDING (element) = curpending;
1266
1267     if (curpending != state) {
1268       GST_DEBUG_ELEMENT (GST_CAT_STATES, element, "intermediate: setting state to %s\n",
1269                          gst_element_statename (curpending));
1270     }
1271
1272     /* call the state change function so it can set the state */
1273     oclass = CLASS (element);
1274     if (oclass->change_state)
1275       return_val = (oclass->change_state) (element);
1276
1277     switch (return_val) {
1278       case GST_STATE_FAILURE:
1279         GST_DEBUG_ELEMENT (GST_CAT_STATES, element, "have failed change_state return\n");
1280         return return_val;
1281       case GST_STATE_ASYNC:
1282         GST_DEBUG_ELEMENT (GST_CAT_STATES, element, "element will change state async\n");
1283         return return_val;
1284       default:
1285         /* Last thing we do is verify that a successful state change really
1286          * did change the state... */
1287         if (GST_STATE (element) != curpending) {
1288           GST_DEBUG_ELEMENT (GST_CAT_STATES, element,
1289                           "element claimed state-change success, but state didn't change %s, %s <-> %s\n",
1290                           gst_element_statename (GST_STATE (element)),
1291                           gst_element_statename (GST_STATE_PENDING (element)),
1292                           gst_element_statename (curpending));
1293           return GST_STATE_FAILURE;
1294         }
1295         break;
1296     }
1297   }
1298
1299   return return_val;
1300 }
1301
1302 static gboolean
1303 gst_element_negotiate_pads (GstElement *element)
1304 {
1305   GList *pads = GST_ELEMENT_PADS (element);
1306
1307   GST_DEBUG_ELEMENT (GST_CAT_CAPS, element, "negotiating pads\n");
1308
1309   while (pads) {
1310     GstPad *pad = GST_PAD (pads->data);
1311     GstRealPad *srcpad;
1312
1313     pads = g_list_next (pads);
1314
1315     if (!GST_IS_REAL_PAD (pad))
1316       continue;
1317
1318     srcpad = GST_PAD_REALIZE (pad);
1319
1320     /* if we have a connection on this pad and it doesn't have caps
1321      * allready, try to negotiate */
1322     if (GST_PAD_IS_CONNECTED (srcpad) && !GST_PAD_CAPS (srcpad)) {
1323       GstRealPad *sinkpad;
1324       GstElementState otherstate;
1325       GstElement *parent;
1326
1327       sinkpad = GST_RPAD_PEER (GST_PAD_REALIZE (srcpad));
1328
1329       /* check the parent of the peer pad, if there is no parent do nothing */
1330       parent = GST_PAD_PARENT (sinkpad);
1331       if (!parent)
1332         continue;
1333
1334       otherstate = GST_STATE (parent);
1335
1336       /* swap pads if needed */
1337       if (!GST_PAD_IS_SRC (srcpad)) {
1338         GstRealPad *temp;
1339
1340         temp = srcpad;
1341         srcpad = sinkpad;
1342         sinkpad = temp;
1343       }
1344
1345       /* only try to negotiate if the peer element is in PAUSED or higher too */
1346       if (otherstate >= GST_STATE_READY) {
1347         GST_DEBUG_ELEMENT (GST_CAT_CAPS, element, "perform negotiate for %s:%s and %s:%s\n",
1348                       GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1349         if (!gst_pad_perform_negotiate (GST_PAD (srcpad), GST_PAD (sinkpad)))
1350           return FALSE;
1351       }
1352       else {
1353         GST_DEBUG_ELEMENT (GST_CAT_CAPS, element, "not negotiatiating %s:%s and %s:%s, not in READY yet\n",
1354                       GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1355       }
1356     }
1357   }
1358
1359   return TRUE;
1360 }
1361
1362 static void
1363 gst_element_clear_pad_caps (GstElement *element)
1364 {
1365   GList *pads = GST_ELEMENT_PADS (element);
1366
1367   GST_DEBUG_ELEMENT (GST_CAT_CAPS, element, "clearing pad caps\n");
1368
1369   while (pads) {
1370     GstRealPad *pad = GST_PAD_REALIZE (pads->data);
1371
1372     if (GST_PAD_CAPS (pad)) {
1373       GST_PAD_CAPS (pad) = NULL;
1374     }
1375     pads = g_list_next (pads);
1376   }
1377 }
1378
1379 static GstElementStateReturn
1380 gst_element_change_state (GstElement *element)
1381 {
1382   GstElementState old_state;
1383   GstObject *parent;
1384   gint old_pending, old_transition;
1385
1386   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_FAILURE);
1387
1388   old_state = GST_STATE (element);
1389   old_pending = GST_STATE_PENDING (element);
1390   old_transition = GST_STATE_TRANSITION (element);
1391
1392   if (old_pending == GST_STATE_VOID_PENDING || old_state == GST_STATE_PENDING (element)) {
1393     GST_INFO (GST_CAT_STATES, "no state change needed for element %s (VOID_PENDING)", GST_ELEMENT_NAME (element));
1394     return GST_STATE_SUCCESS;
1395   }
1396
1397   GST_INFO (GST_CAT_STATES, "%s default handler sets state from %s to %s %d", GST_ELEMENT_NAME (element),
1398                      gst_element_statename (old_state),
1399                      gst_element_statename (old_pending),
1400                      GST_STATE_TRANSITION (element));
1401
1402   /* we set the state change early for the negotiation functions */
1403   GST_STATE (element) = old_pending;
1404   GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
1405
1406   /* if we are going to paused, we try to negotiate the pads */
1407   if (old_transition == GST_STATE_NULL_TO_READY) {
1408     if (!gst_element_negotiate_pads (element))
1409       goto failure;
1410   }
1411   /* going to the READY state clears all pad caps */
1412   else if (old_transition == GST_STATE_READY_TO_NULL) {
1413     gst_element_clear_pad_caps (element);
1414   }
1415
1416   /* tell the scheduler if we have one */
1417   if (element->sched) {
1418     if (gst_scheduler_state_transition (element->sched, element, old_transition)
1419                     != GST_STATE_SUCCESS) {
1420       goto failure;
1421     }
1422   }
1423
1424   parent = GST_ELEMENT_PARENT (element);
1425
1426   /* tell our parent about the state change */
1427   if (parent && GST_IS_BIN (parent)) {
1428     gst_bin_child_state_change (GST_BIN (parent), old_state, GST_STATE (element), element);
1429   }
1430
1431   g_signal_emit (G_OBJECT (element), gst_element_signals[STATE_CHANGE],
1432                   0, old_state, GST_STATE (element));
1433
1434   /* signal the state change in case somebody is waiting for us */
1435   g_mutex_lock (element->state_mutex);
1436   g_cond_signal (element->state_cond);
1437   g_mutex_unlock (element->state_mutex);
1438
1439   return GST_STATE_SUCCESS;
1440
1441 failure:
1442   /* undo the state change */
1443   GST_STATE (element) = old_state;
1444   GST_STATE_PENDING (element) = old_pending;
1445
1446   return GST_STATE_FAILURE;
1447 }
1448
1449 /**
1450  * gst_element_get_factory:
1451  * @element: element to request the factory
1452  *
1453  * Retrieves the factory that was used to create this element
1454  *
1455  * Returns: the factory used for creating this element
1456  */
1457 GstElementFactory*
1458 gst_element_get_factory (GstElement *element)
1459 {
1460   GstElementClass *oclass;
1461
1462   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1463
1464   oclass = CLASS (element);
1465
1466   return oclass->elementfactory;
1467 }
1468
1469 static void
1470 gst_element_dispose (GObject *object)
1471 {
1472   GstElement *element = GST_ELEMENT (object);
1473   GList *pads;
1474   GstPad *pad;
1475
1476   GST_DEBUG_ELEMENT (GST_CAT_REFCOUNTING, element, "dispose\n");
1477
1478   gst_element_set_state (element, GST_STATE_NULL);
1479
1480   /* first we break all our connections with the ouside */
1481   if (element->pads) {
1482     GList *orig;
1483     orig = pads = g_list_copy (element->pads);
1484     while (pads) {
1485       pad = GST_PAD (pads->data);
1486
1487       if (GST_PAD_PEER (pad)) {
1488         GST_DEBUG (GST_CAT_REFCOUNTING, "disconnecting pad '%s'",
1489                         GST_OBJECT_NAME (GST_OBJECT (GST_PAD (GST_PAD_PEER (pad)))));
1490         gst_pad_disconnect (pad, GST_PAD (GST_PAD_PEER (pad)));
1491       }
1492       gst_element_remove_pad (element, pad);
1493
1494       pads = g_list_next (pads);
1495     }
1496     g_list_free (orig);
1497     g_list_free (element->pads);
1498     element->pads = NULL;
1499   }
1500
1501   element->numsrcpads = 0;
1502   element->numsinkpads = 0;
1503   element->numpads = 0;
1504   g_mutex_free (element->state_mutex);
1505   g_cond_free (element->state_cond);
1506
1507   G_OBJECT_CLASS (parent_class)->dispose (object);
1508 }
1509
1510 #ifndef GST_DISABLE_LOADSAVE
1511 /**
1512  * gst_element_save_thyself:
1513  * @element: GstElement to save
1514  * @parent: the xml parent node
1515  *
1516  * Saves the element as part of the given XML structure
1517  *
1518  * Returns: the new xml node
1519  */
1520 static xmlNodePtr
1521 gst_element_save_thyself (GstObject *object,
1522                           xmlNodePtr parent)
1523 {
1524   GList *pads;
1525   GstElementClass *oclass;
1526   GParamSpec **specs, *spec;
1527   gint nspecs, i;
1528   GValue value = { 0, };
1529   GstElement *element;
1530
1531   g_return_val_if_fail (GST_IS_ELEMENT (object), parent);
1532
1533   element = GST_ELEMENT (object);
1534
1535   oclass = CLASS (element);
1536
1537   xmlNewChild(parent, NULL, "name", GST_ELEMENT_NAME(element));
1538
1539   if (oclass->elementfactory != NULL) {
1540     GstElementFactory *factory = (GstElementFactory *)oclass->elementfactory;
1541
1542     xmlNewChild (parent, NULL, "type", GST_OBJECT_NAME (factory));
1543     xmlNewChild (parent, NULL, "version", factory->details->version);
1544   }
1545
1546 /* FIXME: what is this? */
1547 /*  if (element->manager) */
1548 /*    xmlNewChild(parent, NULL, "manager", GST_ELEMENT_NAME(element->manager)); */
1549
1550   /* params */
1551   specs = g_object_class_list_properties (G_OBJECT_GET_CLASS (object), &nspecs);
1552
1553   for (i=0; i<nspecs; i++) {
1554     spec = specs[i];
1555     if (spec->flags & G_PARAM_READABLE) {
1556       xmlNodePtr param;
1557
1558       g_value_init(&value, G_PARAM_SPEC_VALUE_TYPE (spec));
1559
1560       g_object_get_property (G_OBJECT (element), spec->name, &value);
1561       param = xmlNewChild (parent, NULL, "param", NULL);
1562       xmlNewChild (param, NULL, "name", spec->name);
1563
1564       if (G_IS_PARAM_SPEC_STRING (spec))
1565         xmlNewChild (param, NULL, "value", g_value_dup_string (&value));
1566       else if (G_IS_PARAM_SPEC_ENUM (spec))
1567         xmlNewChild (param, NULL, "value", g_strdup_printf ("%d", g_value_get_enum (&value)));
1568       else if (G_IS_PARAM_SPEC_INT64 (spec))
1569         xmlNewChild (param, NULL, "value", g_strdup_printf ("%lld", g_value_get_int64 (&value)));
1570       else
1571         xmlNewChild (param, NULL, "value", g_strdup_value_contents (&value));
1572
1573       g_value_unset(&value);
1574     }
1575   }
1576
1577   pads = GST_ELEMENT_PADS (element);
1578
1579   while (pads) {
1580     GstPad *pad = GST_PAD (pads->data);
1581     /* figure out if it's a direct pad or a ghostpad */
1582     if (GST_ELEMENT (GST_OBJECT_PARENT (pad)) == element) {
1583       xmlNodePtr padtag = xmlNewChild (parent, NULL, "pad", NULL);
1584       gst_object_save_thyself (GST_OBJECT (pad), padtag);
1585     }
1586     pads = g_list_next (pads);
1587   }
1588
1589   return parent;
1590 }
1591
1592 static void
1593 gst_element_restore_thyself (GstObject *object, xmlNodePtr self)
1594 {
1595   xmlNodePtr children;
1596   GstElement *element;
1597   guchar *name = NULL;
1598   guchar *value = NULL;
1599
1600   element = GST_ELEMENT (object);
1601   g_return_if_fail (element != NULL);
1602
1603   /* parameters */
1604   children = self->xmlChildrenNode;
1605   while (children) {
1606     if (!strcmp (children->name, "param")) {
1607       xmlNodePtr child = children->xmlChildrenNode;
1608
1609       while (child) {
1610         if (!strcmp (child->name, "name")) {
1611           name = xmlNodeGetContent (child);
1612         }
1613         else if (!strcmp (child->name, "value")) {
1614           value = xmlNodeGetContent (child);
1615         }
1616         child = child->next;
1617       }
1618       /* FIXME: can this just be g_object_set ? */
1619       gst_util_set_object_arg ((GObject *)G_OBJECT (element), name, value);
1620     }
1621     children = children->next;
1622   }
1623
1624   /* pads */
1625   children = self->xmlChildrenNode;
1626   while (children) {
1627     if (!strcmp (children->name, "pad")) {
1628       gst_pad_load_and_connect (children, GST_OBJECT (element));
1629     }
1630     children = children->next;
1631   }
1632
1633   if (GST_OBJECT_CLASS(parent_class)->restore_thyself)
1634     (GST_OBJECT_CLASS(parent_class)->restore_thyself) (object, self);
1635 }
1636 #endif /* GST_DISABLE_LOADSAVE */
1637
1638 /**
1639  * gst_element_yield:
1640  * @element: Element to yield
1641  *
1642  * Request a yield operation for the child. The scheduler will typically
1643  * give control to another element.
1644  */
1645 void
1646 gst_element_yield (GstElement *element)
1647 {
1648   if (GST_ELEMENT_SCHED (element)) {
1649     gst_scheduler_yield (GST_ELEMENT_SCHED (element), element);
1650   }
1651 }
1652
1653 /**
1654  * gst_element_interrupt:
1655  * @element: Element to interrupt
1656  *
1657  * Request the scheduler of this element to interrupt the execution of
1658  * this element and scheduler another one.
1659  *
1660  * Returns: a boolean indicating that the child should exit its chain/loop/get
1661  * function ASAP, depending on the scheduler implementation.
1662  */
1663 gboolean
1664 gst_element_interrupt (GstElement *element)
1665 {
1666   if (GST_ELEMENT_SCHED (element)) {
1667     return gst_scheduler_interrupt (GST_ELEMENT_SCHED (element), element);
1668   }
1669   else
1670     return FALSE;
1671 }
1672
1673 /**
1674  * gst_element_set_sched:
1675  * @element: Element to set manager of.
1676  * @sched: @GstScheduler to set.
1677  *
1678  * Sets the scheduler of the element.  For internal use only, unless you're
1679  * writing a new bin subclass.
1680  */
1681 void
1682 gst_element_set_sched (GstElement *element,
1683                        GstScheduler *sched)
1684 {
1685   g_return_if_fail (GST_IS_ELEMENT (element));
1686
1687   GST_INFO_ELEMENT (GST_CAT_PARENTAGE, element, "setting scheduler to %p", sched);
1688
1689   element->sched = sched;
1690 }
1691
1692 /**
1693  * gst_element_get_sched:
1694  * @element: Element to get manager of.
1695  *
1696  * Returns the scheduler of the element.
1697  *
1698  * Returns: Element's scheduler
1699  */
1700 GstScheduler*
1701 gst_element_get_sched (GstElement *element)
1702 {
1703   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1704
1705   return element->sched;
1706 }
1707
1708 /**
1709  * gst_element_set_loop_function:
1710  * @element: Element to set loop function of.
1711  * @loop: Pointer to loop function.
1712  *
1713  * This sets the loop function for the element.  The function pointed to
1714  * can deviate from the GstElementLoopFunction definition in type of
1715  * pointer only.
1716  *
1717  * NOTE: in order for this to take effect, the current loop function *must*
1718  * exit.  Assuming the loop function itself is the only one who will cause
1719  * a new loopfunc to be assigned, this should be no problem.
1720  */
1721 void
1722 gst_element_set_loop_function (GstElement *element,
1723                                GstElementLoopFunction loop)
1724 {
1725   g_return_if_fail (GST_IS_ELEMENT (element));
1726
1727   /* set the loop function */
1728   element->loopfunc = loop;
1729
1730   /* set the NEW_LOOPFUNC flag so everyone knows to go try again */
1731   GST_FLAG_SET (element, GST_ELEMENT_NEW_LOOPFUNC);
1732 }
1733
1734 /**
1735  * gst_element_set_eos:
1736  * @element: element to set to the EOS state
1737  *
1738  * Perform the actions needed to bring the element in the EOS state.
1739  */
1740 void
1741 gst_element_set_eos (GstElement *element)
1742 {
1743   g_return_if_fail (GST_IS_ELEMENT (element));
1744
1745   GST_DEBUG (GST_CAT_EVENT, "setting EOS on element %s", GST_OBJECT_NAME (element));
1746
1747   gst_element_set_state (element, GST_STATE_PAUSED);
1748
1749   g_signal_emit (G_OBJECT (element), gst_element_signals[EOS], 0);
1750 }
1751
1752
1753 /**
1754  * gst_element_statename:
1755  * @state: The state to get the name of
1756  *
1757  * Gets a string representing the given state.
1758  *
1759  * Returns: a string with the statename.
1760  */
1761 const gchar*
1762 gst_element_statename (GstElementState state)
1763 {
1764   switch (state) {
1765 #ifdef GST_DEBUG_COLOR
1766     case GST_STATE_VOID_PENDING: return "NONE_PENDING";break;
1767     case GST_STATE_NULL: return "\033[01;37mNULL\033[00m";break;
1768     case GST_STATE_READY: return "\033[01;31mREADY\033[00m";break;
1769     case GST_STATE_PLAYING: return "\033[01;32mPLAYING\033[00m";break;
1770     case GST_STATE_PAUSED: return "\033[01;33mPAUSED\033[00m";break;
1771     default: return g_strdup_printf ("\033[01;37;41mUNKNOWN!\033[00m(%d)", state);
1772 #else
1773     case GST_STATE_VOID_PENDING: return "NONE_PENDING";break;
1774     case GST_STATE_NULL: return "NULL";break;
1775     case GST_STATE_READY: return "READY";break;
1776     case GST_STATE_PLAYING: return "PLAYING";break;
1777     case GST_STATE_PAUSED: return "PAUSED";break;
1778     default: return "UNKNOWN!";
1779 #endif
1780   }
1781   return "";
1782 }
1783
1784 static void
1785 gst_element_populate_std_props (GObjectClass * klass,
1786                                 const char *prop_name, guint arg_id, GParamFlags flags)
1787 {
1788   GQuark prop_id = g_quark_from_string (prop_name);
1789   GParamSpec *pspec;
1790
1791   static GQuark fd_id = 0;
1792   static GQuark blocksize_id;
1793   static GQuark bytesperread_id;
1794   static GQuark dump_id;
1795   static GQuark filesize_id;
1796   static GQuark mmapsize_id;
1797   static GQuark location_id;
1798   static GQuark offset_id;
1799   static GQuark silent_id;
1800   static GQuark touch_id;
1801
1802   if (!fd_id) {
1803     fd_id = g_quark_from_static_string ("fd");
1804     blocksize_id = g_quark_from_static_string ("blocksize");
1805     bytesperread_id = g_quark_from_static_string ("bytesperread");
1806     dump_id = g_quark_from_static_string ("dump");
1807     filesize_id = g_quark_from_static_string ("filesize");
1808     mmapsize_id = g_quark_from_static_string ("mmapsize");
1809     location_id = g_quark_from_static_string ("location");
1810     offset_id = g_quark_from_static_string ("offset");
1811     silent_id = g_quark_from_static_string ("silent");
1812     touch_id = g_quark_from_static_string ("touch");
1813   }
1814
1815   if (prop_id == fd_id) {
1816     pspec = g_param_spec_int ("fd", "File-descriptor",
1817                               "File-descriptor for the file being read",
1818                               0, G_MAXINT, 0, flags);
1819   }
1820   else if (prop_id == blocksize_id) {
1821     pspec = g_param_spec_ulong ("blocksize", "Block Size",
1822                                 "Block size to read per buffer",
1823                                 0, G_MAXULONG, 4096, flags);
1824
1825   }
1826   else if (prop_id == bytesperread_id) {
1827     pspec = g_param_spec_int ("bytesperread", "bytesperread",
1828                               "bytesperread",
1829                               G_MININT, G_MAXINT, 0, flags);
1830
1831   }
1832   else if (prop_id == dump_id) {
1833     pspec = g_param_spec_boolean ("dump", "dump", "dump", FALSE, flags);
1834
1835   }
1836   else if (prop_id == filesize_id) {
1837     pspec = g_param_spec_int64 ("filesize", "File Size",
1838                                 "Size of the file being read",
1839                                 0, G_MAXINT64, 0, flags);
1840
1841   }
1842   else if (prop_id == mmapsize_id) {
1843     pspec = g_param_spec_ulong ("mmapsize", "mmap() Block Size",
1844                                 "Size in bytes of mmap()d regions",
1845                                 0, G_MAXULONG, 4 * 1048576, flags);
1846
1847   }
1848   else if (prop_id == location_id) {
1849     pspec = g_param_spec_string ("location", "File Location",
1850                                  "Location of the file to read",
1851                                  NULL, flags);
1852
1853   }
1854   else if (prop_id == offset_id) {
1855     pspec = g_param_spec_int64 ("offset", "File Offset",
1856                                 "Byte offset of current read pointer",
1857                                 0, G_MAXINT64, 0, flags);
1858
1859   }
1860   else if (prop_id == silent_id) {
1861     pspec = g_param_spec_boolean ("silent", "silent", "silent",
1862                                   FALSE, flags);
1863
1864   }
1865   else if (prop_id == touch_id) {
1866     pspec = g_param_spec_boolean ("touch", "Touch read data",
1867                                   "Touch data to force disk read before "
1868                                   "push ()", TRUE, flags);
1869   }
1870   else {
1871     g_warning ("Unknown - 'standard' property '%s' id %d from klass %s",
1872                prop_name, arg_id, g_type_name (G_OBJECT_CLASS_TYPE (klass)));
1873     pspec = NULL;
1874   }
1875
1876   if (pspec) {
1877     g_object_class_install_property (klass, arg_id, pspec);
1878   }
1879 }
1880
1881 /**
1882  * gst_element_class_install_std_props:
1883  * @klass: the class to add the properties to
1884  * @first_name: the first in a NULL terminated
1885  * 'name', 'id', 'flags' triplet list.
1886  * @...: the triplet list
1887  *
1888  * Add a list of standardized properties with types to the @klass.
1889  * the id is for the property switch in your get_prop method, and
1890  * the flags determine readability / writeability.
1891  **/
1892 void
1893 gst_element_class_install_std_props (GstElementClass * klass, const char *first_name, ...)
1894 {
1895   const char *name;
1896
1897   va_list args;
1898
1899   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1900
1901   va_start (args, first_name);
1902
1903   name = first_name;
1904
1905   while (name) {
1906     int arg_id = va_arg (args, int);
1907     int flags = va_arg (args, int);
1908
1909     gst_element_populate_std_props ((GObjectClass *) klass, name, arg_id, flags);
1910
1911     name = va_arg (args, char *);
1912   }
1913
1914   va_end (args);
1915 }
1916
1917 /**
1918  * gst_element_get_managing_bin:
1919  * @element: the element in question
1920  *
1921  * Get the managing bin (a pipeline or a thread, for example) of an element.
1922  *
1923  * Returns: the bin, or NULL on failure
1924  **/
1925 GstBin*
1926 gst_element_get_managing_bin (GstElement *element)
1927 {
1928   GstBin *bin;
1929
1930   g_return_val_if_fail (element != NULL, NULL);
1931
1932   bin = GST_BIN (gst_object_get_parent (GST_OBJECT_CAST (element)));
1933
1934   while (bin && !GST_FLAG_IS_SET (GST_OBJECT_CAST (bin), GST_BIN_FLAG_MANAGER))
1935     bin = GST_BIN (gst_object_get_parent (GST_OBJECT_CAST (bin)));
1936
1937   return bin;
1938 }