/* GStreamer

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

 *                    2000 Wim Taymans <wtay@chello.be>

 *

 * gstpad.c: Pads for linking elements together

 *

 * 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:gstpad

 * @short_description: Object contained by elements that allows links to

 *                     other elements

 * @see_also: #GstPadTemplate, #GstElement, #GstEvent

 *

 * A #GstElement is linked to other elements via "pads", which are extremely

 * light-weight generic link points.

 * After two pads are retrieved from an element with gst_element_get_pad(),

 * the pads can be link with gst_pad_link(). (For quick links,

 * you can also use gst_element_link(), which will make the obvious

 * link for you if it's straightforward.)

 *

 * Pads are typically created from a #GstPadTemplate with

 * gst_pad_new_from_template().

 *

 * Pads have #GstCaps attached to it to describe the media type they are

 * capable of dealing with.  gst_pad_get_caps() and gst_pad_set_caps() are

 * used to manipulate the caps of the pads.

 * Pads created from a pad template cannot set capabilities that are

 * incompatible with the pad template capabilities.

 *

 * Pads without pad templates can be created with gst_pad_new(),

 * which takes a direction and a name as an argument.  If the name is NULL,

 * then a guaranteed unique name will be assigned to it.

 *

 * gst_pad_get_parent() will retrieve the #GstElement that owns the pad.

 *

 * A #GstElement creating a pad will typically use the various

 * gst_pad_set_*_function() calls to register callbacks for various events

 * on the pads.

 *

 * GstElements will use gst_pad_push() and gst_pad_pull_range() to push out

 * or pull in a buffer.

 *

 * To send a #GstEvent on a pad, use gst_pad_send_event() and

 * gst_pad_push_event().

 *

 * Last reviewed on 2006-07-06 (0.10.9)

 */

#include "gst_private.h"

#include "gstpad.h"

#include "gstpadtemplate.h"

#include "gstenumtypes.h"

#include "gstmarshal.h"

#include "gstutils.h"

#include "gstinfo.h"

#include "gsterror.h"

#include "gstvalue.h"

#include "glib-compat-private.h"

#ifdef __SYMBIAN32__

#include <glib_global.h>

#endif

GST_DEBUG_CATEGORY_STATIC (debug_dataflow);

#define GST_CAT_DEFAULT GST_CAT_PADS

/* Pad signals and args */

enum

{

  PAD_LINKED,

  PAD_UNLINKED,

  PAD_REQUEST_LINK,

  PAD_HAVE_DATA,

  /* FILL ME */

  LAST_SIGNAL

};

enum

{

  PAD_PROP_0,

  PAD_PROP_CAPS,

  PAD_PROP_DIRECTION,

  PAD_PROP_TEMPLATE,

  /* FILL ME */

};

static void gst_pad_dispose (GObject * object);

static void gst_pad_finalize (GObject * object);

static void gst_pad_set_property (GObject * object, guint prop_id,

    const GValue * value, GParamSpec * pspec);

static void gst_pad_get_property (GObject * object, guint prop_id,

    GValue * value, GParamSpec * pspec);

static GstFlowReturn handle_pad_block (GstPad * pad);

static GstCaps *gst_pad_get_caps_unlocked (GstPad * pad);

static void gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ);

static gboolean gst_pad_activate_default (GstPad * pad);

static gboolean gst_pad_acceptcaps_default (GstPad * pad, GstCaps * caps);

#ifndef GST_DISABLE_LOADSAVE

static xmlNodePtr gst_pad_save_thyself (GstObject * object, xmlNodePtr parent);

#endif

static GstObjectClass *parent_class = NULL;

static guint gst_pad_signals[LAST_SIGNAL] = { 0 };

/* quarks for probe signals */

static GQuark buffer_quark;

static GQuark event_quark;

typedef struct

{

  const gint ret;

  const gchar *name;

  GQuark quark;

} GstFlowQuarks;

static GstFlowQuarks flow_quarks[] = {

  {GST_FLOW_CUSTOM_SUCCESS, "custom-success", 0},

  {GST_FLOW_RESEND, "resend", 0},

  {GST_FLOW_OK, "ok", 0},

  {GST_FLOW_NOT_LINKED, "not-linked", 0},

  {GST_FLOW_WRONG_STATE, "wrong-state", 0},

  {GST_FLOW_UNEXPECTED, "unexpected", 0},

  {GST_FLOW_NOT_NEGOTIATED, "not-negotiated", 0},

  {GST_FLOW_ERROR, "error", 0},

  {GST_FLOW_NOT_SUPPORTED, "not-supported", 0},

};

/**

 * gst_flow_get_name:

 * @ret: a #GstFlowReturn to get the name of.

 *

 * Gets a string representing the given flow return.

 *

 * Returns: a static string with the name of the flow return.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

G_CONST_RETURN gchar *

gst_flow_get_name (GstFlowReturn ret)

{

  gint i;

  ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);

    if (ret == flow_quarks[i].ret)

      return flow_quarks[i].name;

  }

  return "unknown";

}

/**

 * gst_flow_to_quark:

 * @ret: a #GstFlowReturn to get the quark of.

 *

 * Get the unique quark for the given GstFlowReturn.

 *

 * Returns: the quark associated with the flow return or 0 if an

 * invalid return was specified.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GQuark

gst_flow_to_quark (GstFlowReturn ret)

{

  gint i;

  ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);

    if (ret == flow_quarks[i].ret)

      return flow_quarks[i].quark;

  }

  return 0;

}

}

static gboolean

_gst_do_pass_data_accumulator (GSignalInvocationHint * ihint,

    GValue * return_accu, const GValue * handler_return, gpointer dummy)

{

  gboolean ret = g_value_get_boolean (handler_return);

  GST_DEBUG ("accumulated %d", ret);

  g_value_set_boolean (return_accu, ret);

  return ret;

}

static gboolean

default_have_data (GstPad * pad, GstMiniObject * o)

{

  return TRUE;

}

static void

gst_pad_class_init (GstPadClass * klass)

{

  GObjectClass *gobject_class;

  GstObjectClass *gstobject_class;

  gobject_class = G_OBJECT_CLASS (klass);

  gstobject_class = GST_OBJECT_CLASS (klass);

  parent_class = g_type_class_peek_parent (klass);

  gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_pad_dispose);

  gobject_class->finalize = GST_DEBUG_FUNCPTR (gst_pad_finalize);

  gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_pad_set_property);

  gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_pad_get_property);

  /**

   * GstPad::linked:

   * @pad: the pad that emitted the signal

   * @peer: the peer pad that has been connected

   *

   * Signals that a pad has been linked to the peer pad.

   */

  gst_pad_signals[PAD_LINKED] =

      g_signal_new ("linked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,

      G_STRUCT_OFFSET (GstPadClass, linked), NULL, NULL,

      gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);

  /**

   * GstPad::unlinked:

   * @pad: the pad that emitted the signal

   * @peer: the peer pad that has been disconnected

   *

   * Signals that a pad has been unlinked from the peer pad.

   */

  gst_pad_signals[PAD_UNLINKED] =

      g_signal_new ("unlinked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,

      G_STRUCT_OFFSET (GstPadClass, unlinked), NULL, NULL,

      gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);

  /**

   * GstPad::request-link:

   * @pad: the pad that emitted the signal

   * @peer: the peer pad for which a connection is requested

   *

   * Signals that a pad connection has been requested.

   */

  gst_pad_signals[PAD_REQUEST_LINK] =

      g_signal_new ("request-link", G_TYPE_FROM_CLASS (klass),

      G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstPadClass, request_link), NULL,

      NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 0);

  /**

   * GstPad::have-data:

   * @pad: the pad that emitted the signal

   * @mini_obj: new data

   *

   * Signals that new data is available on the pad. This signal is used

   * internally for implementing pad probes.

   * See gst_pad_add_*_probe functions.

   *

   * Returns: %TRUE to keep the data, %FALSE to drop it

   */

  gst_pad_signals[PAD_HAVE_DATA] =

      g_signal_new ("have-data", G_TYPE_FROM_CLASS (klass),

      G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,

      G_STRUCT_OFFSET (GstPadClass, have_data),

      _gst_do_pass_data_accumulator,

      NULL, gst_marshal_BOOLEAN__POINTER, G_TYPE_BOOLEAN, 1,

      GST_TYPE_MINI_OBJECT);

  g_object_class_install_property (gobject_class, PAD_PROP_CAPS,

      g_param_spec_boxed ("caps", "Caps", "The capabilities of the pad",

  g_object_class_install_property (gobject_class, PAD_PROP_DIRECTION,

      g_param_spec_enum ("direction", "Direction", "The direction of the pad",

          GST_TYPE_PAD_DIRECTION, GST_PAD_UNKNOWN,

  /* FIXME, Make G_PARAM_CONSTRUCT_ONLY when we fix ghostpads. */

  g_object_class_install_property (gobject_class, PAD_PROP_TEMPLATE,

      g_param_spec_object ("template", "Template",

          "The GstPadTemplate of this pad", GST_TYPE_PAD_TEMPLATE,

#ifndef GST_DISABLE_LOADSAVE

  gstobject_class->save_thyself = GST_DEBUG_FUNCPTR (gst_pad_save_thyself);

#endif

  gstobject_class->path_string_separator = ".";

  klass->have_data = default_have_data;

}

static void

gst_pad_init (GstPad * pad)

{

  GST_PAD_DIRECTION (pad) = GST_PAD_UNKNOWN;

  GST_PAD_PEER (pad) = NULL;

  GST_PAD_CHAINFUNC (pad) = NULL;

  GST_PAD_LINKFUNC (pad) = NULL;

  GST_PAD_CAPS (pad) = NULL;

  GST_PAD_GETCAPSFUNC (pad) = NULL;

  GST_PAD_ACTIVATEFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_activate_default);

  GST_PAD_EVENTFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_event_default);

  GST_PAD_QUERYTYPEFUNC (pad) =

      GST_DEBUG_FUNCPTR (gst_pad_get_query_types_default);

  GST_PAD_QUERYFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_query_default);

  GST_PAD_INTLINKFUNC (pad) =

      GST_DEBUG_FUNCPTR (gst_pad_get_internal_links_default);

  GST_PAD_ACCEPTCAPSFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_acceptcaps_default);

  pad->do_buffer_signals = 0;

  pad->do_event_signals = 0;

  GST_PAD_SET_FLUSHING (pad);

  pad->preroll_lock = g_mutex_new ();

  pad->preroll_cond = g_cond_new ();

  pad->stream_rec_lock = g_new (GStaticRecMutex, 1);

  g_static_rec_mutex_init (pad->stream_rec_lock);

  pad->block_cond = g_cond_new ();

}

static void

gst_pad_dispose (GObject * object)

{

  GstPad *pad = GST_PAD (object);

  GstPad *peer;

  GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, pad, "dispose");

  /* unlink the peer pad */

  if ((peer = gst_pad_get_peer (pad))) {

    /* window for MT unsafeness, someone else could unlink here

     * and then we call unlink with wrong pads. The unlink

     * function would catch this and safely return failed. */

    if (GST_PAD_IS_SRC (pad))

      gst_pad_unlink (pad, peer);

    else

      gst_pad_unlink (peer, pad);

    gst_object_unref (peer);

  }

  /* clear the caps */

  gst_caps_replace (&GST_PAD_CAPS (pad), NULL);

  gst_pad_set_pad_template (pad, NULL);

  G_OBJECT_CLASS (parent_class)->dispose (object);

}

static void

gst_pad_finalize (GObject * object)

{

  GstPad *pad = GST_PAD (object);

  GstTask *task;

  /* in case the task is still around, clean it up */

  if ((task = GST_PAD_TASK (pad))) {

    gst_task_join (task);

    GST_PAD_TASK (pad) = NULL;

    gst_object_unref (task);

  }

  if (pad->stream_rec_lock) {

    g_static_rec_mutex_free (pad->stream_rec_lock);

    g_free (pad->stream_rec_lock);

    pad->stream_rec_lock = NULL;

  }

  if (pad->preroll_lock) {

    g_mutex_free (pad->preroll_lock);

    g_cond_free (pad->preroll_cond);

    pad->preroll_lock = NULL;

    pad->preroll_cond = NULL;

  }

  if (pad->block_cond) {

    g_cond_free (pad->block_cond);

    pad->block_cond = NULL;

  }

  G_OBJECT_CLASS (parent_class)->finalize (object);

}

static void

gst_pad_set_property (GObject * object, guint prop_id,

    const GValue * value, GParamSpec * pspec)

{

  g_return_if_fail (GST_IS_PAD (object));

  switch (prop_id) {

    case PAD_PROP_DIRECTION:

      GST_PAD_DIRECTION (object) = g_value_get_enum (value);

      break;

    case PAD_PROP_TEMPLATE:

      gst_pad_set_pad_template (GST_PAD_CAST (object),

          (GstPadTemplate *) g_value_get_object (value));

      break;

    default:

      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);

      break;

  }

}

static void

gst_pad_get_property (GObject * object, guint prop_id,

    GValue * value, GParamSpec * pspec)

{

  g_return_if_fail (GST_IS_PAD (object));

  switch (prop_id) {

    case PAD_PROP_CAPS:

      GST_OBJECT_LOCK (object);

      g_value_set_boxed (value, GST_PAD_CAPS (object));

      GST_OBJECT_UNLOCK (object);

      break;

    case PAD_PROP_DIRECTION:

      g_value_set_enum (value, GST_PAD_DIRECTION (object));

      break;

    case PAD_PROP_TEMPLATE:

      g_value_set_object (value, GST_PAD_PAD_TEMPLATE (object));

      break;

    default:

      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);

      break;

  }

}

/**

 * gst_pad_new:

 * @name: the name of the new pad.

 * @direction: the #GstPadDirection of the pad.

 *

 * Creates a new pad with the given name in the given direction.

 * If name is NULL, a guaranteed unique name (across all pads)

 * will be assigned.

 * This function makes a copy of the name so you can safely free the name.

 *

 * Returns: a new #GstPad, or NULL in case of an error.

 *

 * MT safe.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstPad *

gst_pad_new (const gchar * name, GstPadDirection direction)

{

  return g_object_new (GST_TYPE_PAD,

      "name", name, "direction", direction, NULL);

}

/**

 * gst_pad_new_from_template:

 * @templ: the pad template to use

 * @name: the name of the element

 *

 * Creates a new pad with the given name from the given template.

 * If name is NULL, a guaranteed unique name (across all pads)

 * will be assigned.

 * This function makes a copy of the name so you can safely free the name.

 *

 * Returns: a new #GstPad, or NULL in case of an error.

 */