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