/**
* SECTION:gstiterator
+ * @title: GstIterator
* @short_description: Object to retrieve multiple elements in a threadsafe
* way.
* @see_also: #GstElement, #GstBin
* Various GStreamer objects provide access to their internal structures using
* an iterator.
*
- * In general, whenever calling a GstIterator function results in your code
- * receiving a refcounted object, the refcount for that object will have been
- * increased. Your code is responsible for unreffing that object after use.
+ * Note that if calling a GstIterator function results in your code receiving
+ * a refcounted object (with, say, g_value_get_object()), the refcount for that
+ * object will not be increased. Your code is responsible for taking a reference
+ * if it wants to continue using it later.
*
* The basic use pattern of an iterator is as follows:
- * |[
+ * |[<!-- language="C" -->
* GstIterator *it = _get_iterator(object);
+ * GValue item = G_VALUE_INIT;
* done = FALSE;
* while (!done) {
* switch (gst_iterator_next (it, &item)) {
* case GST_ITERATOR_OK:
- * ... use/change item here...
+ * ...get/use/change item here...
* g_value_reset (&item);
* break;
* case GST_ITERATOR_RESYNC:
* g_value_unset (&item);
* gst_iterator_free (it);
* ]|
- *
- * Last reviewed on 2009-06-16 (0.10.24)
*/
#include "gst_private.h"
* Create a new iterator designed for iterating @list.
*
* The list you iterate is usually part of a data structure @owner and is
- * protected with @lock.
+ * protected with @lock.
*
* The iterator will use @lock to retrieve the next item of the list and it
* will then call the @item function before releasing @lock again.
* @it: The #GstIterator to iterate
* @elem: (out caller-allocates): pointer to hold next element
*
- * Get the next item from the iterator in @elem.
+ * Get the next item from the iterator in @elem.
*
* Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid
* value. @elem must have been initialized to the type of the iterator or
*
* A return value of %GST_ITERATOR_RESYNC indicates that the element list was
* concurrently updated. The user of @it should call gst_iterator_resync() to
- * get the newly updated list.
+ * get the newly updated list.
*
* A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error.
*
* This procedure can be used (and is used internally) to implement the
* gst_iterator_foreach() and gst_iterator_find_custom() operations.
*
- * The fold will proceed as long as @func returns TRUE. When the iterator has no
- * more arguments, %GST_ITERATOR_DONE will be returned. If @func returns FALSE,
+ * The fold will proceed as long as @func returns %TRUE. When the iterator has no
+ * more arguments, %GST_ITERATOR_DONE will be returned. If @func returns %FALSE,
* the fold will stop, and %GST_ITERATOR_OK will be returned. Errors or resyncs
* will cause fold to return %GST_ITERATOR_ERROR or %GST_ITERATOR_RESYNC as
* appropriate.
GValue item = { 0, };
GstIteratorResult result;
+ g_return_val_if_fail (it != NULL, GST_ITERATOR_ERROR);
+
while (1) {
result = gst_iterator_next (it, &item);
switch (result) {
}
fold_done:
+
+#if GLIB_CHECK_VERSION (2, 48, 0)
g_value_unset (&item);
+#else
+ if (item.g_type != 0)
+ g_value_unset (&item);
+#endif
return result;
}
*
* The iterator will not be freed.
*
- * This function will return FALSE if an error happened to the iterator
+ * This function will return %FALSE if an error happened to the iterator
* or if the element wasn't found.
*
- * Returns: Returns TRUE if the element was found, else FALSE.
+ * Returns: Returns %TRUE if the element was found, else %FALSE.
*
* MT safe.
*/