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