iterator: API: Add gst_iterator_new_single()

This allows "iteration" over a single object of some type,
which happens often for the GstPadIterIntLinksFunction for example.

docs/gst/gstreamer-sections.txt

@@ -1069,6 +1069,7 @@ GstIteratorItemFunction
 GstIteratorResyncFunction
 GstIteratorFreeFunction
 GstIteratorFoldFunction
+GstCopyFunction
 
 GST_ITERATOR
 GST_ITERATOR_LOCK
@@ -1077,6 +1078,7 @@ GST_ITERATOR_ORIG_COOKIE
 
 gst_iterator_new
 gst_iterator_new_list
+gst_iterator_new_single
 
 gst_iterator_next
 gst_iterator_resync

gst/gstiterator.c

@@ -658,3 +658,80 @@ gst_iterator_find_custom (GstIterator * it, GCompareFunc func,
   /* no need to unset, it's just a pointer */
   return g_value_get_pointer (&ret);
 }
+
+typedef struct
+{
+  GstIterator parent;
+  gpointer object;
+  GstCopyFunction copy;
+  GFreeFunc free;
+  gboolean visited;
+} GstSingleObjectIterator;
+
+static guint32 _single_object_dummy_cookie = 0;
+
+static GstIteratorResult
+gst_single_object_iterator_iterator_next (GstSingleObjectIterator * it,
+    gpointer * result)
+{
+  if (it->visited) {
+    *result = NULL;
+    return GST_ITERATOR_DONE;
+  }
+
+  *result = it->copy (it->object);
+  return GST_ITERATOR_OK;
+}
+
+static void
+gst_single_object_iterator_resync (GstSingleObjectIterator * it)
+{
+  it->visited = FALSE;
+}
+
+static void
+gst_single_object_iterator_free (GstSingleObjectIterator * it)
+{
+  it->free (it->object);
+  g_free (it);
+}
+
+/**
+ * gst_iterator_new:
+ * @type: #GType of the passed object
+ * @object: object that this iterator should return
+ * @copy: Function that returns a copy of @object or increases it's refcount
+ * @free: Function to be called for freeing @object
+ *
+ * This #GstIterator is a convenient iterator for the common
+ * case where a #GstIterator needs to be returned but only
+ * a single object has the be considered. This happens often
+ * for the #GstPadIterIntLinkFunction.
+ *
+ * Since: 0.10.25
+ *
+ */
+GstIterator *
+gst_iterator_new_single (GType type, gpointer object, GstCopyFunction copy,
+    GFreeFunc free)
+{
+  GstSingleObjectIterator *result;
+
+  g_return_val_if_fail (object != NULL, NULL);
+  g_return_val_if_fail (copy != NULL, NULL);
+  g_return_val_if_fail (free != NULL, NULL);
+
+  result = (GstSingleObjectIterator *)
+      gst_iterator_new (sizeof (GstSingleObjectIterator),
+      G_TYPE_FROM_INSTANCE (object), NULL, &_single_object_dummy_cookie,
+      (GstIteratorNextFunction) gst_single_object_iterator_iterator_next, NULL,
+      (GstIteratorResyncFunction) gst_single_object_iterator_resync,
+      (GstIteratorFreeFunction) gst_single_object_iterator_free);
+
+  result->object = copy (object);
+  result->copy = copy;
+  result->free = free;
+  result->visited = FALSE;
+
+  return (GstIterator *) result;
+}

gst/gstiterator.h

@@ -137,6 +137,19 @@ typedef void		  (*GstIteratorFreeFunction)	(GstIterator *it);
  */
 typedef gboolean	  (*GstIteratorFoldFunction)    (gpointer item, GValue *ret, gpointer user_data);
 
+/**
+ * GstCopyFunction:
+ * @object: The object to copy
+ *
+ * A function to create a copy of some object or
+ * increase it's reference count.
+ *
+ * Returns: a copy of the object or the same object with increased reference count
+ *
+ * Since: 0.10.25
+ */
+typedef gpointer          (*GstCopyFunction)             (gpointer object);
+
 /**
  * GST_ITERATOR:
  * @it: the #GstIterator value
@@ -226,6 +239,11 @@ GstIterator*		gst_iterator_new_list		(GType type,
 							 GstIteratorItemFunction item,
 							 GstIteratorDisposeFunction free);
 
+GstIterator*            gst_iterator_new_single         (GType type,
+                                                         gpointer object,
+                                                         GstCopyFunction copy,
+                                                         GFreeFunc free);
+
 /* using iterators */
 GstIteratorResult	gst_iterator_next		(GstIterator *it, gpointer *elem);
 void			gst_iterator_resync		(GstIterator *it);