Index: gst/gstutils.c
===================================================================
RCS file: /cvs/gstreamer/gstreamer/gst/gstutils.c,v
retrieving revision 1.132
diff -u -p -r1.132 gstutils.c
--- gst/gstutils.c	28 Jan 2006 00:59:36 -0000	1.132
+++ gst/gstutils.c	31 Jan 2006 09:37:45 -0000
@@ -1,6 +1,7 @@
 /* GStreamer
  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
  *                    2000 Wim Taymans <wtay@chello.be>
+ *                    2002 Thomas Vander Stichele <thomas@apestaart.org>
  *
  * gstutils.c: Utility functions: gtk_get_property stuff, etc.
  *
@@ -34,6 +35,7 @@
 #include "gstghostpad.h"
 #include "gstutils.h"
 #include "gstinfo.h"
+#include "gstparse.h"
 #include "gst-i18n-lib.h"
 
 
@@ -2850,3 +2852,173 @@ gst_element_found_tags (GstElement * ele
   gst_element_post_message (element,
       gst_message_new_tag (GST_OBJECT (element), list));
 }
+
+static GstPad *
+element_find_unconnected_pad (GstElement *element, GstPadDirection direction)
+{
+  GstIterator *iter;
+  GstPad *unconnected_pad = NULL;
+  gboolean done;
+
+  switch (direction) {
+    case GST_PAD_SRC:
+      iter = gst_element_iterate_src_pads (element);
+      break;
+    case GST_PAD_SINK:
+      iter = gst_element_iterate_sink_pads (element);
+      break;
+    default:
+      g_assert_not_reached ();
+  }
+
+  done = FALSE;
+  while (!done) {
+    gpointer pad;
+
+    switch (gst_iterator_next (iter, &pad)) {
+      case GST_ITERATOR_OK: {
+        GstPad *peer;
+
+        GST_CAT_LOG (GST_CAT_ELEMENT_PADS, "examining pad %s:%s",
+            GST_DEBUG_PAD_NAME (pad));
+
+        peer = gst_pad_get_peer (GST_PAD (pad));
+        if (peer == NULL) {
+          unconnected_pad = pad;
+          done = TRUE;
+          GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
+              "found existing unlinked pad %s:%s",
+              GST_DEBUG_PAD_NAME (unconnected_pad));
+        } else {
+          gst_object_unref (pad);
+          gst_object_unref (peer);
+        }
+        break;
+      }
+      case GST_ITERATOR_DONE:
+        done = TRUE;
+        break;
+      case GST_ITERATOR_RESYNC:
+        gst_iterator_resync (iter);
+        break;
+      case GST_ITERATOR_ERROR:
+        g_return_val_if_reached (NULL);
+        break;
+    }
+  }
+
+  gst_iterator_free (iter);
+
+  return unconnected_pad;
+}
+
+/**
+ * gst_bin_find_unconnected_pad:
+ * @bin: bin in which to look for elements with unconnected pads
+ * @direction: whether to look for an unconnected source or sink pad
+ *
+ * Recursively looks for elements with an unconnected pad of the given
+ * direction within the specified bin and returns an unconnected pad
+ * if one is found, or NULL otherwise. If a pad is found, the caller
+ * owns a reference to it and should use gst_object_unref() on the
+ * pad when it is not needed any longer.
+ *
+ * Returns: unconnected pad of the given direction, or NULL.
+ *
+ * Since: 0.10.3
+ */
+GstPad *
+gst_bin_find_unconnected_pad (GstBin * bin, GstPadDirection direction)
+{
+  GstIterator *iter;
+  gboolean done;
+  GstPad *pad = NULL;
+
+  g_return_val_if_fail (GST_IS_BIN (bin), NULL);
+  g_return_val_if_fail (direction != GST_PAD_UNKNOWN, NULL);
+
+  done = FALSE;
+  iter = gst_bin_iterate_recurse (bin);
+  while (!done) {
+    gpointer element;
+
+    switch (gst_iterator_next (iter, &element)) {
+      case GST_ITERATOR_OK:
+        pad = element_find_unconnected_pad (GST_ELEMENT (element), direction);
+        gst_object_unref (element);
+        if (pad != NULL)
+          done = TRUE;
+        break;
+      case GST_ITERATOR_DONE:
+        done = TRUE;
+        break;
+      case GST_ITERATOR_RESYNC:
+        gst_iterator_resync (iter);
+        break;
+      case GST_ITERATOR_ERROR:
+        g_return_val_if_reached (NULL);
+        break;
+    }
+  }
+
+  gst_iterator_free (iter);
+
+  return pad;
+}
+
+/**
+ * gst_parse_bin_from_description:
+ * @bin_description: command line describing the bin
+ * @ghost_unconnected_pads: whether to automatically create ghost pads
+ *                          for unconnected source or sink pads within
+ *                          the bin
+ * @err: where to store the error message in case of an error, or NULL
+ *
+ * This is a convenience wrapper around gst_parse_launch() to create a
+ * #GstBin<!-- -->s from a gst-launch-style pipeline description. See
+ * gst_parse_launch() and the gst-launch man page for details about the
+ * syntax. Ghost pads on the bin for unconnected source or sink pads
+ * within the bin can automatically be created.
+ *
+ * Returns: a newly-created bin, or NULL if an error occurred.
+ *
+ * Since: 0.10.3
+ */
+GstElement *
+gst_parse_bin_from_description (const gchar * bin_description,
+    gboolean ghost_unconnected_pads, GError ** err)
+{
+  GstPad *pad = NULL;
+  GstBin *bin;
+  gchar *desc;
+
+  g_return_val_if_fail (bin_description != NULL, NULL);
+  g_return_val_if_fail (err == NULL || *err == NULL, NULL);
+
+  GST_DEBUG ("Making bin from description '%s'", bin_description);
+
+  /* parse the pipeline to a bin */
+  desc = g_strdup_printf ("bin.( %s )", bin_description);
+  bin = (GstBin *) gst_parse_launch (desc, err);
+  g_free (desc);
+
+  if (bin == NULL || (err && *err != NULL)) {
+    if (bin)
+      gst_object_unref (bin);
+    return NULL;
+  }
+
+  /* find pads and ghost them if necessary */
+  if (ghost_unconnected_pads) {
+    if ((pad = gst_bin_find_unconnected_pad (bin, GST_PAD_SRC))) {
+      gst_element_add_pad (GST_ELEMENT (bin), gst_ghost_pad_new ("src", pad));
+      gst_object_unref (pad);
+    }
+    if ((pad = gst_bin_find_unconnected_pad (bin, GST_PAD_SINK))) {
+      gst_element_add_pad (GST_ELEMENT (bin), gst_ghost_pad_new ("sink", pad));
+      gst_object_unref (pad);
+    }
+  }
+
+  return GST_ELEMENT (bin);
+}
Index: gst/gstutils.h
===================================================================
RCS file: /cvs/gstreamer/gstreamer/gst/gstutils.h,v
retrieving revision 1.70
diff -u -p -r1.70 gstutils.h
--- gst/gstutils.h	2 Jan 2006 20:26:06 -0000	1.70
+++ gst/gstutils.h	31 Jan 2006 09:37:46 -0000
@@ -1,6 +1,7 @@
 /* GStreamer
  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
  *                    2000 Wim Taymans <wtay@chello.be>
+ *                    2002 Thomas Vander Stichele <thomas@apestaart.org>
  *
  * gstutils.h: Header for various utility functions
  *
@@ -565,8 +566,9 @@ gboolean                gst_pad_query_co
 		                                         GstFormat *dest_format, gint64 *dest_val);
 
 /* bin functions */
-void			gst_bin_add_many                (GstBin *bin, GstElement *element_1, ...) G_GNUC_NULL_TERMINATED;
-void			gst_bin_remove_many             (GstBin *bin, GstElement *element_1, ...) G_GNUC_NULL_TERMINATED;
+void                    gst_bin_add_many                (GstBin *bin, GstElement *element_1, ...) G_GNUC_NULL_TERMINATED;
+void                    gst_bin_remove_many             (GstBin *bin, GstElement *element_1, ...) G_GNUC_NULL_TERMINATED;
+GstPad *                gst_bin_find_unconnected_pad    (GstBin *bin, GstPadDirection direction);
 
 /* buffer functions */
 GstBuffer *		gst_buffer_merge		(GstBuffer * buf1, GstBuffer * buf2);
@@ -597,6 +599,11 @@ void			gst_element_found_tags_for_pad	(G
 void			gst_element_found_tags		(GstElement * element,
 							 GstTagList * list);
 
+/* parse utility functions */
+GstElement *            gst_parse_bin_from_description  (const gchar * bin_description,
+                                                         gboolean ghost_unconnected_pads,
+                                                         GError ** err);
+
 G_END_DECLS
 
 #endif /* __GST_UTILS_H__ */
Index: docs/gst/gstreamer-sections.txt
===================================================================
RCS file: /cvs/gstreamer/gstreamer/docs/gst/gstreamer-sections.txt,v
retrieving revision 1.244
diff -u -p -r1.244 gstreamer-sections.txt
--- docs/gst/gstreamer-sections.txt	26 Jan 2006 06:57:13 -0000	1.244
+++ docs/gst/gstreamer-sections.txt	31 Jan 2006 09:37:47 -0000
@@ -52,6 +52,7 @@ gst_bin_iterate_all_by_interface
 <SUBSECTION>
 gst_bin_add_many
 gst_bin_remove_many
+gst_bin_find_unconnected_pad
 
 <SUBSECTION>
 GstBinFlags
@@ -1383,6 +1384,7 @@ GST_PARSE_ERROR
 GstParseError
 gst_parse_launch
 gst_parse_launchv
+gst_parse_bin_from_description
 <SUBSECTION Standard>
 GST_TYPE_PARSE_ERROR
 <SUBSECTION Private>
