From f87630663856e15ef6d6e93b40a1f01f56aaa718 Mon Sep 17 00:00:00 2001
From: Matthew Waters <matthew@centricular.com>
Date: Fri, 25 Mar 2016 01:28:18 +0000
Subject: [PATCH] utils: expose pad_link_maybe_ghosting

This is a useful function to automatically add ghost pads when linking
two elements across bin boundaries without know their exact parentage.

e.g. when using gst_parse_bin_from_description (with or without it ghosting pads),
one can simply retreive the src/sink pads from the bin to link to another pad.

Similar functionality is provided by gst_element_link_pads{_full}() however only
by pad name rather than by actual pads.

API: gst_pad_link_maybe_ghosting_full

https://bugzilla.gnome.org/show_bug.cgi?id=764176
---
 docs/gst/gstreamer-sections.txt |  1 +
 gst/gstutils.c                  | 32 ++++++++++++++++++++++++++++++++
 gst/gstutils.h                  |  3 +++
 win32/common/libgstreamer.def   |  1 +
 4 files changed, 37 insertions(+)

diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt
index e9bd81969b..d5451e1a43 100644
--- a/docs/gst/gstreamer-sections.txt
+++ b/docs/gst/gstreamer-sections.txt
@@ -1819,6 +1819,7 @@ gst_pad_get_pad_template
 
 gst_pad_link
 gst_pad_link_full
+gst_pad_link_maybe_ghosting_full
 gst_pad_unlink
 gst_pad_is_linked
 gst_pad_can_link
diff --git a/gst/gstutils.c b/gst/gstutils.c
index 69458c05c6..9e3cbb316d 100644
--- a/gst/gstutils.c
+++ b/gst/gstutils.c
@@ -1518,6 +1518,38 @@ pad_link_maybe_ghosting (GstPad * src, GstPad * sink, GstPadLinkCheck flags)
   return ret;
 }
 
+/**
+ * gst_pad_link_maybe_ghosting_full:
+ * @src: a #GstPad
+ * @sink: a #GstPad
+ * @flags: some #GstPadLinkCheck flags
+ *
+ * Links @src to @sink, creating any #GstGhostPad's in between as necessary.
+ *
+ * This is a convenience function to save having to create and add intermediate
+ * #GstGhostPad's as required for linking across #GstBin boundaries.
+ *
+ * If @src or @sink pads don't have parent elements or do not share a common
+ * ancestor, the link will fail.
+ *
+ * Calling gst_pad_link_maybe_ghosting_full() with
+ * @flags == %GST_PAD_LINK_CHECK_DEFAULT is the recommended way of linking
+ * pads with safety checks applied.
+ *
+ * Returns: whether the link succeeded.
+ *
+ * Since: 1.10
+ */
+gboolean
+gst_pad_link_maybe_ghosting_full (GstPad * src, GstPad * sink,
+    GstPadLinkCheck flags)
+{
+  g_return_val_if_fail (GST_IS_PAD (src), FALSE);
+  g_return_val_if_fail (GST_IS_PAD (sink), FALSE);
+
+  return pad_link_maybe_ghosting (src, sink, flags);
+}
+
 static void
 release_and_unref_pad (GstElement * element, GstPad * pad, gboolean requestpad)
 {
diff --git a/gst/gstutils.h b/gst/gstutils.h
index 457a76a0f6..cd7b1cd9ec 100644
--- a/gst/gstutils.h
+++ b/gst/gstutils.h
@@ -924,6 +924,9 @@ gboolean                gst_pad_query_convert           (GstPad *pad, GstFormat
 GstCaps *               gst_pad_query_caps              (GstPad *pad, GstCaps *filter);
 gboolean                gst_pad_query_accept_caps       (GstPad *pad, GstCaps *caps);
 
+gboolean                gst_pad_link_maybe_ghosting_full (GstPad            *src,
+                                                          GstPad            *sink,
+                                                          GstPadLinkCheck   flags);
 
 gboolean                gst_pad_peer_query_position     (GstPad *pad, GstFormat format, gint64 *cur);
 gboolean                gst_pad_peer_query_duration     (GstPad *pad, GstFormat format, gint64 *duration);
diff --git a/win32/common/libgstreamer.def b/win32/common/libgstreamer.def
index 3fa3c401aa..c41c86a032 100644
--- a/win32/common/libgstreamer.def
+++ b/win32/common/libgstreamer.def
@@ -857,6 +857,7 @@ EXPORTS
 	gst_pad_link_check_get_type
 	gst_pad_link_full
 	gst_pad_link_get_name
+	gst_pad_link_maybe_ghosting_full
 	gst_pad_link_return_get_type
 	gst_pad_mark_reconfigure
 	gst_pad_mode_get_name