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

@@ -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

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)
 {

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);

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