/* GStreamer

 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>

 *                    2004 Wim Taymans <wim@fluendo.com>

 *

 * gstelement.c: The base element, all elements derive from this

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Library General Public

 * License as published by the Free Software Foundation; either

 * version 2 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Library General Public License for more details.

 *

 * You should have received a copy of the GNU Library General Public

 * License along with this library; if not, write to the

 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,

 * Boston, MA 02111-1307, USA.

 */

/**

 * SECTION:gstelement

 * @short_description: Abstract base class for all pipeline elements

 * @see_also: #GstElementFactory, #GstPad

 *

 * GstElement is the abstract base class needed to construct an element that

 * can be used in a GStreamer pipeline. Please refer to the plugin writers

 * guide for more information on creating #GstElement subclasses.

 *

 * The name of a #GstElement can be get with gst_element_get_name() and set with

 * gst_element_set_name().  For speed, GST_ELEMENT_NAME() can be used in the

 * core when using the appropriate locking. Do not use this in plug-ins or

 * applications in order to retain ABI compatibility.

 *

 * All elements have pads (of the type #GstPad).  These pads link to pads on

 * other elements.  #GstBuffer flow between these linked pads.

 * A #GstElement has a #GList of #GstPad structures for all their input (or sink)

 * and output (or source) pads.

 * Core and plug-in writers can add and remove pads with gst_element_add_pad()

 * and gst_element_remove_pad().

 *

 * A pad of an element can be retrieved by name with gst_element_get_pad().

 * An iterator of all pads can be retrieved with gst_element_iterate_pads().

 *

 * Elements can be linked through their pads.

 * If the link is straightforward, use the gst_element_link()

 * convenience function to link two elements, or gst_element_link_many()

 * for more elements in a row.

 * Use gst_element_link_filtered() to link two elements constrained by

 * a specified set of #GstCaps.

 * For finer control, use gst_element_link_pads() and

 * gst_element_link_pads_filtered() to specify the pads to link on

 * each element by name.

 *

 * Each element has a state (see #GstState).  You can get and set the state

 * of an element with gst_element_get_state() and gst_element_set_state().

 * To get a string representation of a #GstState, use

 * gst_element_state_get_name().

 *

 * You can get and set a #GstClock on an element using gst_element_get_clock()

 * and gst_element_set_clock().

 * Some elements can provide a clock for the pipeline if

 * gst_element_provides_clock() returns %TRUE. With the

 * gst_element_provide_clock() method one can retrieve the clock provided by

 * such an element.

 * Not all elements require a clock to operate correctly. If

 * gst_element_requires_clock() returns %TRUE, a clock should be set on the

 * element with gst_element_set_clock().

 *

 * Note that clock slection and distribution is normally handled by the

 * toplevel #GstPipeline so the clock functions are only to be used in very

 * specific situations.

 *

 * Last reviewed on 2006-03-12 (0.10.5)

 */

#include "gst_private.h"

#include <glib.h>

#include <stdarg.h>

#include <gobject/gvaluecollector.h>

#include "gstelement.h"

#include "gstenumtypes.h"

#include "gstbus.h"

#include "gstmarshal.h"

#include "gsterror.h"

#include "gstevent.h"

#include "gstutils.h"

#include "gstinfo.h"

#include "gst-i18n-lib.h"

#ifdef __SYMBIAN32__

#include <glib_global.h>

#endif

/* Element signals and args */

enum

{

  PAD_ADDED,

  PAD_REMOVED,

  NO_MORE_PADS,

  /* add more above */

  LAST_SIGNAL

};

enum

{

  ARG_0

      /* FILL ME */

};

extern void __gst_element_details_clear (GstElementDetails * dp);

extern void __gst_element_details_copy (GstElementDetails * dest,

    const GstElementDetails * src);

static void gst_element_class_init (GstElementClass * klass);

static void gst_element_init (GstElement * element);

static void gst_element_base_class_init (gpointer g_class);

static void gst_element_base_class_finalize (gpointer g_class);

static void gst_element_dispose (GObject * object);

static void gst_element_finalize (GObject * object);

static GstStateChangeReturn gst_element_change_state_func (GstElement * element,

    GstStateChange transition);

static GstStateChangeReturn gst_element_get_state_func (GstElement * element,

    GstState * state, GstState * pending, GstClockTime timeout);

static GstStateChangeReturn gst_element_set_state_func (GstElement * element,

    GstState state);

static void gst_element_set_bus_func (GstElement * element, GstBus * bus);

static gboolean gst_element_default_send_event (GstElement * element,

    GstEvent * event);

static gboolean gst_element_default_query (GstElement * element,

    GstQuery * query);

static GstPadTemplate

    * gst_element_class_get_request_pad_template (GstElementClass *

    element_class, const gchar * name);

#ifndef GST_DISABLE_LOADSAVE

static xmlNodePtr gst_element_save_thyself (GstObject * object,

    xmlNodePtr parent);

static void gst_element_restore_thyself (GstObject * parent, xmlNodePtr self);

#endif

static GstObjectClass *parent_class = NULL;

static guint gst_element_signals[LAST_SIGNAL] = { 0 };

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GType

gst_element_get_type (void)

{

  static GType gst_element_type = 0;

  if (G_UNLIKELY (gst_element_type == 0)) {

    static const GTypeInfo element_info = {

      sizeof (GstElementClass),

      gst_element_base_class_init,

      gst_element_base_class_finalize,

      (GClassInitFunc) gst_element_class_init,

      NULL,

      NULL,

      sizeof (GstElement),

      0,

      (GInstanceInitFunc) gst_element_init,

      NULL

    };

    gst_element_type = g_type_register_static (GST_TYPE_OBJECT, "GstElement",

        &element_info, G_TYPE_FLAG_ABSTRACT);

  }

  return gst_element_type;

}

static void

gst_element_class_init (GstElementClass * klass)

{

  GObjectClass *gobject_class;

  GstObjectClass *gstobject_class;

  gobject_class = (GObjectClass *) klass;

  gstobject_class = (GstObjectClass *) klass;

  parent_class = g_type_class_peek_parent (klass);

  /**

   * GstElement::pad-added:

   * @gstelement: the object which received the signal

   * @new_pad: the pad that has been added

   *

   * a new #GstPad has been added to the element.

   */

  gst_element_signals[PAD_ADDED] =

      g_signal_new ("pad-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,

      G_STRUCT_OFFSET (GstElementClass, pad_added), NULL, NULL,

      gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);

  /**

   * GstElement::pad-removed:

   * @gstelement: the object which received the signal

   * @old_pad: the pad that has been removed

   *

   * a #GstPad has been removed from the element

   */

  gst_element_signals[PAD_REMOVED] =

      g_signal_new ("pad-removed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,

      G_STRUCT_OFFSET (GstElementClass, pad_removed), NULL, NULL,

      gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);

  /**

   * GstElement::no-more-pads:

   * @gstelement: the object which received the signal

   *

   * This signals that the element will not generate more dynamic pads.

   */

  gst_element_signals[NO_MORE_PADS] =

      g_signal_new ("no-more-pads", G_TYPE_FROM_CLASS (klass),

      G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstElementClass, no_more_pads), NULL,

      NULL, gst_marshal_VOID__VOID, G_TYPE_NONE, 0);

  gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_element_dispose);

  gobject_class->finalize = GST_DEBUG_FUNCPTR (gst_element_finalize);

#ifndef GST_DISABLE_LOADSAVE

  gstobject_class->save_thyself = GST_DEBUG_FUNCPTR (gst_element_save_thyself);

  gstobject_class->restore_thyself =

      GST_DEBUG_FUNCPTR (gst_element_restore_thyself);

#endif

  klass->change_state = GST_DEBUG_FUNCPTR (gst_element_change_state_func);

  klass->set_state = GST_DEBUG_FUNCPTR (gst_element_set_state_func);

  klass->get_state = GST_DEBUG_FUNCPTR (gst_element_get_state_func);

  klass->set_bus = GST_DEBUG_FUNCPTR (gst_element_set_bus_func);

  klass->query = GST_DEBUG_FUNCPTR (gst_element_default_query);

  klass->send_event = GST_DEBUG_FUNCPTR (gst_element_default_send_event);

  klass->numpadtemplates = 0;

  klass->elementfactory = NULL;

}

static void

gst_element_base_class_init (gpointer g_class)

{

  GstElementClass *element_class = GST_ELEMENT_CLASS (g_class);

  /* FIXME 0.11: Copy the element details and instead of clearing the

   * pad template list copy the list and increase the refcount of

   * the pad templates by one.

   *

   * This will make it possible to add pad templates and set element

   * details in the class_init functions and is the real GObject way

   * of doing things.

   * See http://bugzilla.gnome.org/show_bug.cgi?id=491501

   */

  memset (&element_class->details, 0, sizeof (GstElementDetails));

  element_class->padtemplates = NULL;

}

static void

gst_element_base_class_finalize (gpointer g_class)

{

  GstElementClass *klass = GST_ELEMENT_CLASS (g_class);

  g_list_foreach (klass->padtemplates, (GFunc) gst_object_unref, NULL);

  g_list_free (klass->padtemplates);

  __gst_element_details_clear (&klass->details);

}

static void

gst_element_init (GstElement * element)

{

  GST_STATE (element) = GST_STATE_NULL;

  GST_STATE_TARGET (element) = GST_STATE_NULL;

  GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;

  GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;

  GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;

  element->state_lock = g_new0 (GStaticRecMutex, 1);

  g_static_rec_mutex_init (element->state_lock);

  element->state_cond = g_cond_new ();

}

/**

 * gst_element_default_error:

 * @object: a #GObject that signalled the error.

 * @orig: the #GstObject that initiated the error.

 * @error: the GError.

 * @debug: an additional debug information string, or %NULL.

 *

 * A default error signal callback to attach to an element.

 * The user data passed to the g_signal_connect is ignored.

 *

 * The default handler will simply print the error string using g_print.

 *

 * MT safe.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_element_default_error (GObject * object, GstObject * source, GError * error,

    gchar * debug)

{

  gchar *name = gst_object_get_path_string (source);

  g_print (_("ERROR: from element %s: %s\n"), name, error->message);

  if (debug)

    g_print (_("Additional debug info:\n%s\n"), debug);

  g_free (name);

}

/**

 * gst_element_release_request_pad:

 * @element: a #GstElement to release the request pad of.

 * @pad: the #GstPad to release.

 *

 * Makes the element free the previously requested pad as obtained

 * with gst_element_get_request_pad().

 *

 * MT safe.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_element_release_request_pad (GstElement * element, GstPad * pad)

{

  GstElementClass *oclass;

  g_return_if_fail (GST_IS_ELEMENT (element));

  g_return_if_fail (GST_IS_PAD (pad));

  oclass = GST_ELEMENT_GET_CLASS (element);

  /* if the element implements a custom release function we call that, else we

   * simply remove the pad from the element */

  if (oclass->release_pad)

    (oclass->release_pad) (element, pad);

  else

    gst_element_remove_pad (element, pad);

}

/**

 * gst_element_requires_clock:

 * @element: a #GstElement to query

 *

 * Query if the element requires a clock.

 *

 * Returns: %TRUE if the element requires a clock

 *

 * MT safe.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

gboolean

gst_element_requires_clock (GstElement * element)

{

  gboolean result;

  g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);

  result = (GST_ELEMENT_GET_CLASS (element)->set_clock != NULL);

  return result;

}

/**

 * gst_element_provides_clock:

 * @element: a #GstElement to query

 *

 * Query if the element provides a clock. A #GstClock provided by an

 * element can be used as the global #GstClock for the pipeline.

 * An element that can provide a clock is only required to do so in the PAUSED

 * state, this means when it is fully negotiated and has allocated the resources

 * to operate the clock.

 *

 * Returns: %TRUE if the element provides a clock

 *

 * MT safe.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

gboolean

gst_element_provides_clock (GstElement * element)

{

  gboolean result;

  g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);

  result = (GST_ELEMENT_GET_CLASS (element)->provide_clock != NULL);

  return result;

}

/**

 * gst_element_provide_clock:

 * @element: a #GstElement to query

 *

 * Get the clock provided by the given element.

 * <note>An element is only required to provide a clock in the PAUSED

 * state. Some elements can provide a clock in other states.</note>

 *

 * Returns: the GstClock provided by the element or %NULL

 * if no clock could be provided.  Unref after usage.

 *

 * MT safe.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstClock *

gst_element_provide_clock (GstElement * element)

{

  GstClock *result = NULL;

  GstElementClass *oclass;

  g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);

  oclass = GST_ELEMENT_GET_CLASS (element);

  if (oclass->provide_clock)

    result = oclass->provide_clock (element);

  return result;

}

/**

 * gst_element_set_clock:

 * @element: a #GstElement to set the clock for.

 * @clock: the #GstClock to set for the element.

 *

 * Sets the clock for the element. This function increases the

 * refcount on the clock. Any previously set clock on the object

 * is unreffed.

 *

 * Returns: %TRUE if the element accepted the clock. An element can refuse a

 * clock when it, for example, is not able to slave its internal clock to the

 * @clock or when it requires a specific clock to operate.

 *

 * MT safe.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

gboolean

gst_element_set_clock (GstElement * element, GstClock * clock)

{

  GstElementClass *oclass;

  gboolean res = TRUE;

  GstClock **clock_p;

  g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);

  oclass = GST_ELEMENT_GET_CLASS (element);

  GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element, "setting clock %p", clock);

  if (oclass->set_clock)

    res = oclass->set_clock (element, clock);

  if (res) {

    /* only update the clock pointer if the element accepted the clock */

    GST_OBJECT_LOCK (element);

    clock_p = &element->clock;

    gst_object_replace ((GstObject **) clock_p, (GstObject *) clock);

    GST_OBJECT_UNLOCK (element);

  }

  return res;

}

/**

 * gst_element_get_clock:

 * @element: a #GstElement to get the clock of.

 *

 * Gets the currently configured clock of the element. This is the clock as was

 * last set with gst_element_set_clock().

 *

 * Returns: the #GstClock of the element. unref after usage.

 *

 * MT safe.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstClock *

gst_element_get_clock (GstElement * element)

{

  GstClock *result;

  g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);

  GST_OBJECT_LOCK (element);

  if ((result = element->clock))

    gst_object_ref (result);

  GST_OBJECT_UNLOCK (element);

  return result;

}

/**

 * gst_element_set_base_time:

 * @element: a #GstElement.

 * @time: the base time to set.

 *

 * Set the base time of an element. See gst_element_get_base_time().

 *

 * MT safe.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_element_set_base_time (GstElement * element, GstClockTime time)