wearable/docs/gst/html/gstreamer-GstIterator.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>GstIterator</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GStreamer 0.10 Core Reference Manual">
   8 <link rel="up" href="libgstreamer.html" title="GStreamer Core Library">
   9 <link rel="prev" href="GstIndexFactory.html" title="GstIndexFactory">
  10 <link rel="next" href="gstreamer-GstMessage.html" title="GstMessage">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="GstIndexFactory.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="libgstreamer.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GStreamer 0.10 Core Reference Manual</th>
  21 <td><a accesskey="n" href="gstreamer-GstMessage.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#gstreamer-GstIterator.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#gstreamer-GstIterator.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="gstreamer-GstIterator"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="gstreamer-GstIterator.top_of_page"></a>GstIterator</span></h2>
  34 <p>GstIterator — Object to retrieve multiple elements in a threadsafe
  35 way.</p>
  36 </td>
  37 <td valign="top" align="right"></td>
  38 </tr></table></div>
  39 <div class="refsynopsisdiv">
  40 <a name="gstreamer-GstIterator.synopsis"></a><h2>Synopsis</h2>
  41 <pre class="synopsis">
  42 #include &lt;gst/gst.h&gt;
  43
  44 struct              <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator">GstIterator</a>;
  45 enum                <a class="link" href="gstreamer-GstIterator.html#GstIteratorItem" title="enum GstIteratorItem">GstIteratorItem</a>;
  46 enum                <a class="link" href="gstreamer-GstIterator.html#GstIteratorResult" title="enum GstIteratorResult">GstIteratorResult</a>;
  47 <span class="returnvalue">void</span>                (<a class="link" href="gstreamer-GstIterator.html#GstIteratorDisposeFunction" title="GstIteratorDisposeFunction ()">*GstIteratorDisposeFunction</a>)       (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> owner</code></em>);
  48 <a class="link" href="gstreamer-GstIterator.html#GstIteratorResult" title="enum GstIteratorResult"><span class="returnvalue">GstIteratorResult</span></a>   (<a class="link" href="gstreamer-GstIterator.html#GstIteratorNextFunction" title="GstIteratorNextFunction ()">*GstIteratorNextFunction</a>)          (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
  49                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> *result</code></em>);
  50 <a class="link" href="gstreamer-GstIterator.html#GstIteratorItem" title="enum GstIteratorItem"><span class="returnvalue">GstIteratorItem</span></a>     (<a class="link" href="gstreamer-GstIterator.html#GstIteratorItemFunction" title="GstIteratorItemFunction ()">*GstIteratorItemFunction</a>)          (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
  51                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> item</code></em>);
  52 <span class="returnvalue">void</span>                (<a class="link" href="gstreamer-GstIterator.html#GstIteratorResyncFunction" title="GstIteratorResyncFunction ()">*GstIteratorResyncFunction</a>)        (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>);
  53 <span class="returnvalue">void</span>                (<a class="link" href="gstreamer-GstIterator.html#GstIteratorFreeFunction" title="GstIteratorFreeFunction ()">*GstIteratorFreeFunction</a>)          (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>);
  54 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            (<a class="link" href="gstreamer-GstIterator.html#GstIteratorFoldFunction" title="GstIteratorFoldFunction ()">*GstIteratorFoldFunction</a>)          (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> item</code></em>,
  55                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> *ret</code></em>,
  56                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  57 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a>            (<a class="link" href="gstreamer-GstIterator.html#GstCopyFunction" title="GstCopyFunction ()">*GstCopyFunction</a>)                  (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> object</code></em>);
  58 #define             <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR:CAPS" title="GST_ITERATOR()">GST_ITERATOR</a>                        (it)
  59 #define             <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-LOCK:CAPS" title="GST_ITERATOR_LOCK()">GST_ITERATOR_LOCK</a>                   (it)
  60 #define             <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-COOKIE:CAPS" title="GST_ITERATOR_COOKIE()">GST_ITERATOR_COOKIE</a>                 (it)
  61 #define             <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-ORIG-COOKIE:CAPS" title="GST_ITERATOR_ORIG_COOKIE()">GST_ITERATOR_ORIG_COOKIE</a>            (it)
  62 <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="returnvalue">GstIterator</span></a> *       <a class="link" href="gstreamer-GstIterator.html#gst-iterator-new" title="gst_iterator_new ()">gst_iterator_new</a>                    (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> size</code></em>,
  63                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>,
  64                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Threads.html#GMutex"><span class="type">GMutex</span></a> *lock</code></em>,
  65                                                          <em class="parameter"><code><span class="type">guint32</span> *master_cookie</code></em>,
  66                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorNextFunction" title="GstIteratorNextFunction ()"><span class="type">GstIteratorNextFunction</span></a> next</code></em>,
  67                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorItemFunction" title="GstIteratorItemFunction ()"><span class="type">GstIteratorItemFunction</span></a> item</code></em>,
  68                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorResyncFunction" title="GstIteratorResyncFunction ()"><span class="type">GstIteratorResyncFunction</span></a> resync</code></em>,
  69                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorFreeFunction" title="GstIteratorFreeFunction ()"><span class="type">GstIteratorFreeFunction</span></a> free</code></em>);
  70 <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="returnvalue">GstIterator</span></a> *       <a class="link" href="gstreamer-GstIterator.html#gst-iterator-new-list" title="gst_iterator_new_list ()">gst_iterator_new_list</a>               (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>,
  71                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Threads.html#GMutex"><span class="type">GMutex</span></a> *lock</code></em>,
  72                                                          <em class="parameter"><code><span class="type">guint32</span> *master_cookie</code></em>,
  73                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#GList"><span class="type">GList</span></a> **list</code></em>,
  74                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> owner</code></em>,
  75                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorItemFunction" title="GstIteratorItemFunction ()"><span class="type">GstIteratorItemFunction</span></a> item</code></em>,
  76                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorDisposeFunction" title="GstIteratorDisposeFunction ()"><span class="type">GstIteratorDisposeFunction</span></a> free</code></em>);
  77 <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="returnvalue">GstIterator</span></a> *       <a class="link" href="gstreamer-GstIterator.html#gst-iterator-new-single" title="gst_iterator_new_single ()">gst_iterator_new_single</a>             (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>,
  78                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> object</code></em>,
  79                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstCopyFunction" title="GstCopyFunction ()"><span class="type">GstCopyFunction</span></a> copy</code></em>,
  80                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Miscellaneous-Utility-Functions.html#GFreeFunc"><span class="type">GFreeFunc</span></a> free</code></em>);
  81 <a class="link" href="gstreamer-GstIterator.html#GstIteratorResult" title="enum GstIteratorResult"><span class="returnvalue">GstIteratorResult</span></a>   <a class="link" href="gstreamer-GstIterator.html#gst-iterator-next" title="gst_iterator_next ()">gst_iterator_next</a>                   (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
  82                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> *elem</code></em>);
  83 <span class="returnvalue">void</span>                <a class="link" href="gstreamer-GstIterator.html#gst-iterator-resync" title="gst_iterator_resync ()">gst_iterator_resync</a>                 (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>);
  84 <span class="returnvalue">void</span>                <a class="link" href="gstreamer-GstIterator.html#gst-iterator-free" title="gst_iterator_free ()">gst_iterator_free</a>                   (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>);
  85 <span class="returnvalue">void</span>                <a class="link" href="gstreamer-GstIterator.html#gst-iterator-push" title="gst_iterator_push ()">gst_iterator_push</a>                   (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
  86                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *other</code></em>);
  87 <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="returnvalue">GstIterator</span></a> *       <a class="link" href="gstreamer-GstIterator.html#gst-iterator-filter" title="gst_iterator_filter ()">gst_iterator_filter</a>                 (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
  88                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#GCompareFunc"><span class="type">GCompareFunc</span></a> func</code></em>,
  89                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  90 <a class="link" href="gstreamer-GstIterator.html#GstIteratorResult" title="enum GstIteratorResult"><span class="returnvalue">GstIteratorResult</span></a>   <a class="link" href="gstreamer-GstIterator.html#gst-iterator-fold" title="gst_iterator_fold ()">gst_iterator_fold</a>                   (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
  91                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorFoldFunction" title="GstIteratorFoldFunction ()"><span class="type">GstIteratorFoldFunction</span></a> func</code></em>,
  92                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> *ret</code></em>,
  93                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  94 <a class="link" href="gstreamer-GstIterator.html#GstIteratorResult" title="enum GstIteratorResult"><span class="returnvalue">GstIteratorResult</span></a>   <a class="link" href="gstreamer-GstIterator.html#gst-iterator-foreach" title="gst_iterator_foreach ()">gst_iterator_foreach</a>                (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
  95                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#GFunc"><span class="type">GFunc</span></a> func</code></em>,
  96                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  97 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="gstreamer-GstIterator.html#gst-iterator-find-custom" title="gst_iterator_find_custom ()">gst_iterator_find_custom</a>            (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
  98                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#GCompareFunc"><span class="type">GCompareFunc</span></a> func</code></em>,
  99                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
 100 </pre>
 101 </div>
 102 <div class="refsect1">
 103 <a name="gstreamer-GstIterator.description"></a><h2>Description</h2>
 104 <p>
 105 A GstIterator is used to retrieve multiple objects from another object in
 106 a threadsafe way.
 107 </p>
 108 <p>
 109 Various GStreamer objects provide access to their internal structures using
 110 an iterator.
 111 </p>
 112 <p>
 113 In general, whenever calling a GstIterator function results in your code
 114 receiving a refcounted object, the refcount for that object will have been
 115 increased.  Your code is responsible for unrefing that object after use.
 116 </p>
 117 <p>
 118 The basic use pattern of an iterator is as follows:
 119 </p>
 120 <p>
 121 </p>
 122 <div class="example">
 123 <a name="idp18069616"></a><p class="title"><b>Example 13. Using an iterator</b></p>
 124 <div class="example-contents">
 125   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 126     <tbody>
 127       <tr>
 128         <td class="listing_lines" align="right"><pre>1
 129 2
 130 3
 131 4
 132 5
 133 6
 134 7
 135 8
 136 9
 137 10
 138 11
 139 12
 140 13
 141 14
 142 15
 143 16
 144 17
 145 18
 146 19
 147 20
 148 21
 149 22</pre></td>
 150         <td class="listing_code"><pre class="programlisting">it <span class="gtkdoc opt">=</span> <span class="function">_get_iterator</span><span class="gtkdoc opt">(</span>object<span class="gtkdoc opt">);</span>
 151 done <span class="gtkdoc opt">=</span> FALSE<span class="gtkdoc opt">;</span>
 152 <span class="keyword">while</span> <span class="gtkdoc opt">(!</span>done<span class="gtkdoc opt">) {</span>
 153   <span class="keyword">switch</span> <span class="gtkdoc opt">(</span><span class="function"><a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstIterator.html#gst-iterator-next">gst_iterator_next</a></span> <span class="gtkdoc opt">(</span>it<span class="gtkdoc opt">, &amp;</span>item<span class="gtkdoc opt">)) {</span>
 154     <span class="keyword">case</span> GST_ITERATOR_OK<span class="gtkdoc opt">:</span>
 155       <span class="gtkdoc opt">...</span> use<span class="gtkdoc opt">/</span>change item here<span class="gtkdoc opt">...</span>
 156       <span class="function"><a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstObject.html#gst-object-unref">gst_object_unref</a></span> <span class="gtkdoc opt">(</span>item<span class="gtkdoc opt">);</span>
 157       <span class="keyword">break</span><span class="gtkdoc opt">;</span>
 158     <span class="keyword">case</span> GST_ITERATOR_RESYNC<span class="gtkdoc opt">:</span>
 159       <span class="gtkdoc opt">...</span>rollback changes to items<span class="gtkdoc opt">...</span>
 160       <span class="function"><a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstIterator.html#gst-iterator-resync">gst_iterator_resync</a></span> <span class="gtkdoc opt">(</span>it<span class="gtkdoc opt">);</span>
 161       <span class="keyword">break</span><span class="gtkdoc opt">;</span>
 162     <span class="keyword">case</span> GST_ITERATOR_ERROR<span class="gtkdoc opt">:</span>
 163       <span class="gtkdoc opt">...</span>wrong parameters were given<span class="gtkdoc opt">...</span>
 164       done <span class="gtkdoc opt">=</span> TRUE<span class="gtkdoc opt">;</span>
 165       <span class="keyword">break</span><span class="gtkdoc opt">;</span>
 166     <span class="keyword">case</span> GST_ITERATOR_DONE<span class="gtkdoc opt">:</span>
 167       done <span class="gtkdoc opt">=</span> TRUE<span class="gtkdoc opt">;</span>
 168       <span class="keyword">break</span><span class="gtkdoc opt">;</span>
 169   <span class="gtkdoc opt">}</span>
 170 <span class="gtkdoc opt">}</span>
 171 <span class="function"><a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstIterator.html#gst-iterator-free">gst_iterator_free</a></span> <span class="gtkdoc opt">(</span>it<span class="gtkdoc opt">);</span></pre></td>
 172       </tr>
 173     </tbody>
 174   </table>
 175 </div>
 176
 177 </div>
 178 <p><br class="example-break">
 179 </p>
 180 <p>
 181 Last reviewed on 2009-06-16 (0.10.24)
 182 </p>
 183 </div>
 184 <div class="refsect1">
 185 <a name="gstreamer-GstIterator.details"></a><h2>Details</h2>
 186 <div class="refsect2">
 187 <a name="GstIterator"></a><h3>struct GstIterator</h3>
 188 <pre class="programlisting">struct GstIterator {
 189 };
 190 </pre>
 191 <p>
 192 <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> base structure. The values of this structure are
 193 protected for subclasses, use the methods to use the <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a>.
 194 </p>
 195 <div class="variablelist"><table border="0">
 196 <col align="left" valign="top">
 197 <tbody></tbody>
 198 </table></div>
 199 </div>
 200 <hr>
 201 <div class="refsect2">
 202 <a name="GstIteratorItem"></a><h3>enum GstIteratorItem</h3>
 203 <pre class="programlisting">typedef enum {
 204   GST_ITERATOR_ITEM_SKIP = 0,
 205   GST_ITERATOR_ITEM_PASS = 1,
 206   GST_ITERATOR_ITEM_END         = 2
 207 } GstIteratorItem;
 208 </pre>
 209 <p>
 210 The result of a <a class="link" href="gstreamer-GstIterator.html#GstIteratorItemFunction" title="GstIteratorItemFunction ()"><span class="type">GstIteratorItemFunction</span></a>.
 211 </p>
 212 <div class="variablelist"><table border="0">
 213 <col align="left" valign="top">
 214 <tbody>
 215 <tr>
 216 <td><p><a name="GST-ITERATOR-ITEM-SKIP:CAPS"></a><span class="term"><code class="literal">GST_ITERATOR_ITEM_SKIP</code></span></p></td>
 217 <td>Skip this item
 218 </td>
 219 </tr>
 220 <tr>
 221 <td><p><a name="GST-ITERATOR-ITEM-PASS:CAPS"></a><span class="term"><code class="literal">GST_ITERATOR_ITEM_PASS</code></span></p></td>
 222 <td>Return item
 223 </td>
 224 </tr>
 225 <tr>
 226 <td><p><a name="GST-ITERATOR-ITEM-END:CAPS"></a><span class="term"><code class="literal">GST_ITERATOR_ITEM_END</code></span></p></td>
 227 <td>Stop after this item.
 228 </td>
 229 </tr>
 230 </tbody>
 231 </table></div>
 232 </div>
 233 <hr>
 234 <div class="refsect2">
 235 <a name="GstIteratorResult"></a><h3>enum GstIteratorResult</h3>
 236 <pre class="programlisting">typedef enum {
 237   GST_ITERATOR_DONE = 0,
 238   GST_ITERATOR_OK = 1,
 239   GST_ITERATOR_RESYNC = 2,
 240   GST_ITERATOR_ERROR = 3
 241 } GstIteratorResult;
 242 </pre>
 243 <p>
 244 The result of <a class="link" href="gstreamer-GstIterator.html#gst-iterator-next" title="gst_iterator_next ()"><code class="function">gst_iterator_next()</code></a>.
 245 </p>
 246 <div class="variablelist"><table border="0">
 247 <col align="left" valign="top">
 248 <tbody>
 249 <tr>
 250 <td><p><a name="GST-ITERATOR-DONE:CAPS"></a><span class="term"><code class="literal">GST_ITERATOR_DONE</code></span></p></td>
 251 <td>No more items in the iterator
 252 </td>
 253 </tr>
 254 <tr>
 255 <td><p><a name="GST-ITERATOR-OK:CAPS"></a><span class="term"><code class="literal">GST_ITERATOR_OK</code></span></p></td>
 256 <td>An item was retrieved
 257 </td>
 258 </tr>
 259 <tr>
 260 <td><p><a name="GST-ITERATOR-RESYNC:CAPS"></a><span class="term"><code class="literal">GST_ITERATOR_RESYNC</code></span></p></td>
 261 <td>Datastructure changed while iterating
 262 </td>
 263 </tr>
 264 <tr>
 265 <td><p><a name="GST-ITERATOR-ERROR:CAPS"></a><span class="term"><code class="literal">GST_ITERATOR_ERROR</code></span></p></td>
 266 <td>An error happened
 267 </td>
 268 </tr>
 269 </tbody>
 270 </table></div>
 271 </div>
 272 <hr>
 273 <div class="refsect2">
 274 <a name="GstIteratorDisposeFunction"></a><h3>GstIteratorDisposeFunction ()</h3>
 275 <pre class="programlisting"><span class="returnvalue">void</span>                (*GstIteratorDisposeFunction)       (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> owner</code></em>);</pre>
 276 <p>
 277 The function that will be called when a <a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#GList"><span class="type">GList</span></a> iterator is freed. The
 278 owner of the <a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#GList"><span class="type">GList</span></a> iterator can then clean up its resources.
 279 </p>
 280 <div class="variablelist"><table border="0">
 281 <col align="left" valign="top">
 282 <tbody><tr>
 283 <td><p><span class="term"><em class="parameter"><code>owner</code></em> :</span></p></td>
 284 <td>the owner of the iterator</td>
 285 </tr></tbody>
 286 </table></div>
 287 </div>
 288 <hr>
 289 <div class="refsect2">
 290 <a name="GstIteratorNextFunction"></a><h3>GstIteratorNextFunction ()</h3>
 291 <pre class="programlisting"><a class="link" href="gstreamer-GstIterator.html#GstIteratorResult" title="enum GstIteratorResult"><span class="returnvalue">GstIteratorResult</span></a>   (*GstIteratorNextFunction)          (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
 292                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> *result</code></em>);</pre>
 293 <p>
 294 The function that will be called when the next element of the iterator
 295 should be retrieved.
 296 </p>
 297 <p>
 298 Implementors of a <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> should implement this
 299 function and pass it to the constructor of the custom iterator.
 300 The function will be called with the iterator lock held.
 301 </p>
 302 <div class="variablelist"><table border="0">
 303 <col align="left" valign="top">
 304 <tbody>
 305 <tr>
 306 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 307 <td>the iterator</td>
 308 </tr>
 309 <tr>
 310 <td><p><span class="term"><em class="parameter"><code>result</code></em> :</span></p></td>
 311 <td>a pointer to hold the next item</td>
 312 </tr>
 313 <tr>
 314 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 315 <td>the result of the operation.</td>
 316 </tr>
 317 </tbody>
 318 </table></div>
 319 </div>
 320 <hr>
 321 <div class="refsect2">
 322 <a name="GstIteratorItemFunction"></a><h3>GstIteratorItemFunction ()</h3>
 323 <pre class="programlisting"><a class="link" href="gstreamer-GstIterator.html#GstIteratorItem" title="enum GstIteratorItem"><span class="returnvalue">GstIteratorItem</span></a>     (*GstIteratorItemFunction)          (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
 324                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> item</code></em>);</pre>
 325 <p>
 326 The function that will be called after the next item of the iterator
 327 has been retrieved. This function will typically increase the refcount
 328 of the item or make a copy.
 329 </p>
 330 <p>
 331 Implementors of a <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> should implement this
 332 function and pass it to the constructor of the custom iterator.
 333 The function will be called with the iterator lock held.
 334 </p>
 335 <div class="variablelist"><table border="0">
 336 <col align="left" valign="top">
 337 <tbody>
 338 <tr>
 339 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 340 <td>the iterator</td>
 341 </tr>
 342 <tr>
 343 <td><p><span class="term"><em class="parameter"><code>item</code></em> :</span></p></td>
 344 <td>the item being retrieved.</td>
 345 </tr>
 346 <tr>
 347 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 348 <td>the result of the operation.</td>
 349 </tr>
 350 </tbody>
 351 </table></div>
 352 </div>
 353 <hr>
 354 <div class="refsect2">
 355 <a name="GstIteratorResyncFunction"></a><h3>GstIteratorResyncFunction ()</h3>
 356 <pre class="programlisting"><span class="returnvalue">void</span>                (*GstIteratorResyncFunction)        (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>);</pre>
 357 <p>
 358 This function will be called whenever a concurrent update happened
 359 to the iterated datastructure. The implementor of the iterator should
 360 restart the iterator from the beginning and clean up any state it might
 361 have.
 362 </p>
 363 <p>
 364 Implementors of a <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> should implement this
 365 function and pass it to the constructor of the custom iterator.
 366 The function will be called with the iterator lock held.
 367 </p>
 368 <div class="variablelist"><table border="0">
 369 <col align="left" valign="top">
 370 <tbody><tr>
 371 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 372 <td>the iterator</td>
 373 </tr></tbody>
 374 </table></div>
 375 </div>
 376 <hr>
 377 <div class="refsect2">
 378 <a name="GstIteratorFreeFunction"></a><h3>GstIteratorFreeFunction ()</h3>
 379 <pre class="programlisting"><span class="returnvalue">void</span>                (*GstIteratorFreeFunction)          (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>);</pre>
 380 <p>
 381 This function will be called when the iterator is freed.
 382 </p>
 383 <p>
 384 Implementors of a <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> should implement this
 385 function and pass it to the constructor of the custom iterator.
 386 The function will be called with the iterator lock held.
 387 </p>
 388 <div class="variablelist"><table border="0">
 389 <col align="left" valign="top">
 390 <tbody><tr>
 391 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 392 <td>the iterator</td>
 393 </tr></tbody>
 394 </table></div>
 395 </div>
 396 <hr>
 397 <div class="refsect2">
 398 <a name="GstIteratorFoldFunction"></a><h3>GstIteratorFoldFunction ()</h3>
 399 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            (*GstIteratorFoldFunction)          (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> item</code></em>,
 400                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> *ret</code></em>,
 401                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 402 <p>
 403 A function to be passed to <a class="link" href="gstreamer-GstIterator.html#gst-iterator-fold" title="gst_iterator_fold ()"><code class="function">gst_iterator_fold()</code></a>.
 404 </p>
 405 <div class="variablelist"><table border="0">
 406 <col align="left" valign="top">
 407 <tbody>
 408 <tr>
 409 <td><p><span class="term"><em class="parameter"><code>item</code></em> :</span></p></td>
 410 <td>the item to fold</td>
 411 </tr>
 412 <tr>
 413 <td><p><span class="term"><em class="parameter"><code>ret</code></em> :</span></p></td>
 414 <td>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> collecting the result</td>
 415 </tr>
 416 <tr>
 417 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 418 <td>data passed to <a class="link" href="gstreamer-GstIterator.html#gst-iterator-fold" title="gst_iterator_fold ()"><code class="function">gst_iterator_fold()</code></a>
 419 </td>
 420 </tr>
 421 <tr>
 422 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 423 <td>TRUE if the fold should continue, FALSE if it should stop.</td>
 424 </tr>
 425 </tbody>
 426 </table></div>
 427 </div>
 428 <hr>
 429 <div class="refsect2">
 430 <a name="GstCopyFunction"></a><h3>GstCopyFunction ()</h3>
 431 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a>            (*GstCopyFunction)                  (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> object</code></em>);</pre>
 432 <p>
 433 A function to create a copy of some object or
 434 increase its reference count.
 435 </p>
 436 <div class="variablelist"><table border="0">
 437 <col align="left" valign="top">
 438 <tbody>
 439 <tr>
 440 <td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>
 441 <td>The object to copy</td>
 442 </tr>
 443 <tr>
 444 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 445 <td>a copy of the object or the same object with increased reference count</td>
 446 </tr>
 447 </tbody>
 448 </table></div>
 449 <p class="since">Since 0.10.25</p>
 450 </div>
 451 <hr>
 452 <div class="refsect2">
 453 <a name="GST-ITERATOR:CAPS"></a><h3>GST_ITERATOR()</h3>
 454 <pre class="programlisting">#define GST_ITERATOR(it)            ((GstIterator*)(it))
 455 </pre>
 456 <p>
 457 Macro to cast to a <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a>
 458 </p>
 459 <div class="variablelist"><table border="0">
 460 <col align="left" valign="top">
 461 <tbody><tr>
 462 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 463 <td>the <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> value</td>
 464 </tr></tbody>
 465 </table></div>
 466 </div>
 467 <hr>
 468 <div class="refsect2">
 469 <a name="GST-ITERATOR-LOCK:CAPS"></a><h3>GST_ITERATOR_LOCK()</h3>
 470 <pre class="programlisting">#define GST_ITERATOR_LOCK(it)               (GST_ITERATOR(it)-&gt;lock)
 471 </pre>
 472 <p>
 473 Macro to get the lock protecting the datastructure being iterated.
 474 </p>
 475 <div class="variablelist"><table border="0">
 476 <col align="left" valign="top">
 477 <tbody><tr>
 478 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 479 <td>the <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> to get the lock of</td>
 480 </tr></tbody>
 481 </table></div>
 482 </div>
 483 <hr>
 484 <div class="refsect2">
 485 <a name="GST-ITERATOR-COOKIE:CAPS"></a><h3>GST_ITERATOR_COOKIE()</h3>
 486 <pre class="programlisting">#define GST_ITERATOR_COOKIE(it)             (GST_ITERATOR(it)-&gt;cookie)
 487 </pre>
 488 <p>
 489 Macro to get the cookie of a <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a>. The cookie of the
 490 iterator is the value of the master cookie when the iterator
 491 was created.
 492 Whenever the iterator is iterated, the value is compared to the
 493 value of the master cookie. If they are different, a concurrent
 494 modification happened to the iterator and a resync is needed.
 495 </p>
 496 <div class="variablelist"><table border="0">
 497 <col align="left" valign="top">
 498 <tbody><tr>
 499 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 500 <td>the <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> to get the cookie of</td>
 501 </tr></tbody>
 502 </table></div>
 503 </div>
 504 <hr>
 505 <div class="refsect2">
 506 <a name="GST-ITERATOR-ORIG-COOKIE:CAPS"></a><h3>GST_ITERATOR_ORIG_COOKIE()</h3>
 507 <pre class="programlisting">#define GST_ITERATOR_ORIG_COOKIE(it) (GST_ITERATOR(it)-&gt;master_cookie)
 508 </pre>
 509 <p>
 510 Macro to get a pointer to where the master cookie is stored. The
 511 master cookie protects the structure being iterated and gets updated
 512 whenever the datastructure changes.
 513 </p>
 514 <div class="variablelist"><table border="0">
 515 <col align="left" valign="top">
 516 <tbody><tr>
 517 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 518 <td>the <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> to get the master cookie of</td>
 519 </tr></tbody>
 520 </table></div>
 521 </div>
 522 <hr>
 523 <div class="refsect2">
 524 <a name="gst-iterator-new"></a><h3>gst_iterator_new ()</h3>
 525 <pre class="programlisting"><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="returnvalue">GstIterator</span></a> *       gst_iterator_new                    (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> size</code></em>,
 526                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>,
 527                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Threads.html#GMutex"><span class="type">GMutex</span></a> *lock</code></em>,
 528                                                          <em class="parameter"><code><span class="type">guint32</span> *master_cookie</code></em>,
 529                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorNextFunction" title="GstIteratorNextFunction ()"><span class="type">GstIteratorNextFunction</span></a> next</code></em>,
 530                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorItemFunction" title="GstIteratorItemFunction ()"><span class="type">GstIteratorItemFunction</span></a> item</code></em>,
 531                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorResyncFunction" title="GstIteratorResyncFunction ()"><span class="type">GstIteratorResyncFunction</span></a> resync</code></em>,
 532                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorFreeFunction" title="GstIteratorFreeFunction ()"><span class="type">GstIteratorFreeFunction</span></a> free</code></em>);</pre>
 533 <p>
 534 Create a new iterator. This function is mainly used for objects
 535 implementing the next/resync/free function to iterate a data structure.
 536 </p>
 537 <p>
 538 For each item retrieved, the <em class="parameter"><code>item</code></em> function is called with the lock
 539 held. The <em class="parameter"><code>free</code></em> function is called when the iterator is freed.
 540 </p>
 541 <div class="variablelist"><table border="0">
 542 <col align="left" valign="top">
 543 <tbody>
 544 <tr>
 545 <td><p><span class="term"><em class="parameter"><code>size</code></em> :</span></p></td>
 546 <td>the size of the iterator structure</td>
 547 </tr>
 548 <tr>
 549 <td><p><span class="term"><em class="parameter"><code>type</code></em> :</span></p></td>
 550 <td>
 551 <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> of children</td>
 552 </tr>
 553 <tr>
 554 <td><p><span class="term"><em class="parameter"><code>lock</code></em> :</span></p></td>
 555 <td>pointer to a <a href="http://library.gnome.org/devel/glib/unstable/glib-Threads.html#GMutex"><span class="type">GMutex</span></a>.</td>
 556 </tr>
 557 <tr>
 558 <td><p><span class="term"><em class="parameter"><code>master_cookie</code></em> :</span></p></td>
 559 <td>pointer to a guint32 that is changed when the items in the
 560 iterator changed.</td>
 561 </tr>
 562 <tr>
 563 <td><p><span class="term"><em class="parameter"><code>next</code></em> :</span></p></td>
 564 <td>function to get next item</td>
 565 </tr>
 566 <tr>
 567 <td><p><span class="term"><em class="parameter"><code>item</code></em> :</span></p></td>
 568 <td>function to call on each item retrieved</td>
 569 </tr>
 570 <tr>
 571 <td><p><span class="term"><em class="parameter"><code>resync</code></em> :</span></p></td>
 572 <td>function to resync the iterator</td>
 573 </tr>
 574 <tr>
 575 <td><p><span class="term"><em class="parameter"><code>free</code></em> :</span></p></td>
 576 <td>function to free the iterator</td>
 577 </tr>
 578 <tr>
 579 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 580 <td>the new <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a>.
 581 MT safe.</td>
 582 </tr>
 583 </tbody>
 584 </table></div>
 585 </div>
 586 <hr>
 587 <div class="refsect2">
 588 <a name="gst-iterator-new-list"></a><h3>gst_iterator_new_list ()</h3>
 589 <pre class="programlisting"><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="returnvalue">GstIterator</span></a> *       gst_iterator_new_list               (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>,
 590                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Threads.html#GMutex"><span class="type">GMutex</span></a> *lock</code></em>,
 591                                                          <em class="parameter"><code><span class="type">guint32</span> *master_cookie</code></em>,
 592                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#GList"><span class="type">GList</span></a> **list</code></em>,
 593                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> owner</code></em>,
 594                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorItemFunction" title="GstIteratorItemFunction ()"><span class="type">GstIteratorItemFunction</span></a> item</code></em>,
 595                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorDisposeFunction" title="GstIteratorDisposeFunction ()"><span class="type">GstIteratorDisposeFunction</span></a> free</code></em>);</pre>
 596 <p>
 597 Create a new iterator designed for iterating <em class="parameter"><code>list</code></em>.
 598 </p>
 599 <p>
 600 The list you iterate is usually part of a data structure <em class="parameter"><code>owner</code></em> and is
 601 protected with <em class="parameter"><code>lock</code></em>.
 602 </p>
 603 <p>
 604 The iterator will use <em class="parameter"><code>lock</code></em> to retrieve the next item of the list and it
 605 will then call the <em class="parameter"><code>item</code></em> function before releasing <em class="parameter"><code>lock</code></em> again.
 606 </p>
 607 <p>
 608 The <em class="parameter"><code>item</code></em> function usualy makes sure that the item remains alive while
 609 <em class="parameter"><code>lock</code></em> is released and the application is using the item. The application is
 610 responsible for freeing/unreffing the item after usage as explained in
 611 <a class="link" href="gstreamer-GstIterator.html#gst-iterator-next" title="gst_iterator_next ()"><code class="function">gst_iterator_next()</code></a>.
 612 </p>
 613 <p>
 614 When a concurrent update to the list is performed, usually by <em class="parameter"><code>owner</code></em> while
 615 holding <em class="parameter"><code>lock</code></em>, <em class="parameter"><code>master_cookie</code></em> will be updated. The iterator implementation
 616 will notice the update of the cookie and will return <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-RESYNC:CAPS"><code class="literal">GST_ITERATOR_RESYNC</code></a> to
 617 the user of the iterator in the next call to <a class="link" href="gstreamer-GstIterator.html#gst-iterator-next" title="gst_iterator_next ()"><code class="function">gst_iterator_next()</code></a>.
 618 </p>
 619 <p>
 620 <em class="parameter"><code>owner</code></em> will be passed to the <em class="parameter"><code>free</code></em> function when the iterator is freed.
 621 </p>
 622 <div class="variablelist"><table border="0">
 623 <col align="left" valign="top">
 624 <tbody>
 625 <tr>
 626 <td><p><span class="term"><em class="parameter"><code>type</code></em> :</span></p></td>
 627 <td>
 628 <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> of elements</td>
 629 </tr>
 630 <tr>
 631 <td><p><span class="term"><em class="parameter"><code>lock</code></em> :</span></p></td>
 632 <td>pointer to a <a href="http://library.gnome.org/devel/glib/unstable/glib-Threads.html#GMutex"><span class="type">GMutex</span></a> protecting the list.</td>
 633 </tr>
 634 <tr>
 635 <td><p><span class="term"><em class="parameter"><code>master_cookie</code></em> :</span></p></td>
 636 <td>pointer to a guint32 that is incremented when the list
 637 is changed.</td>
 638 </tr>
 639 <tr>
 640 <td><p><span class="term"><em class="parameter"><code>list</code></em> :</span></p></td>
 641 <td>pointer to the list</td>
 642 </tr>
 643 <tr>
 644 <td><p><span class="term"><em class="parameter"><code>owner</code></em> :</span></p></td>
 645 <td>object owning the list</td>
 646 </tr>
 647 <tr>
 648 <td><p><span class="term"><em class="parameter"><code>item</code></em> :</span></p></td>
 649 <td>function to call for each item</td>
 650 </tr>
 651 <tr>
 652 <td><p><span class="term"><em class="parameter"><code>free</code></em> :</span></p></td>
 653 <td>function to call when the iterator is freed</td>
 654 </tr>
 655 <tr>
 656 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 657 <td>the new <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> for <em class="parameter"><code>list</code></em>.
 658 MT safe.</td>
 659 </tr>
 660 </tbody>
 661 </table></div>
 662 </div>
 663 <hr>
 664 <div class="refsect2">
 665 <a name="gst-iterator-new-single"></a><h3>gst_iterator_new_single ()</h3>
 666 <pre class="programlisting"><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="returnvalue">GstIterator</span></a> *       gst_iterator_new_single             (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>,
 667                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> object</code></em>,
 668                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstCopyFunction" title="GstCopyFunction ()"><span class="type">GstCopyFunction</span></a> copy</code></em>,
 669                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Miscellaneous-Utility-Functions.html#GFreeFunc"><span class="type">GFreeFunc</span></a> free</code></em>);</pre>
 670 <p>
 671 This <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> is a convenient iterator for the common
 672 case where a <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> needs to be returned but only
 673 a single object has to be considered. This happens often
 674 for the <a class="link" href="GstPad.html#GstPadIterIntLinkFunction" title="GstPadIterIntLinkFunction ()"><span class="type">GstPadIterIntLinkFunction</span></a>.
 675 </p>
 676 <div class="variablelist"><table border="0">
 677 <col align="left" valign="top">
 678 <tbody>
 679 <tr>
 680 <td><p><span class="term"><em class="parameter"><code>type</code></em> :</span></p></td>
 681 <td>
 682 <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> of the passed object</td>
 683 </tr>
 684 <tr>
 685 <td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>
 686 <td>object that this iterator should return</td>
 687 </tr>
 688 <tr>
 689 <td><p><span class="term"><em class="parameter"><code>copy</code></em> :</span></p></td>
 690 <td>Function that returns a copy of <em class="parameter"><code>object</code></em> or increases its refcount</td>
 691 </tr>
 692 <tr>
 693 <td><p><span class="term"><em class="parameter"><code>free</code></em> :</span></p></td>
 694 <td>Function to be called for freeing <em class="parameter"><code>object</code></em>
 695 </td>
 696 </tr>
 697 <tr>
 698 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 699 <td>the new <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> for <em class="parameter"><code>object</code></em>.</td>
 700 </tr>
 701 </tbody>
 702 </table></div>
 703 <p class="since">Since 0.10.25</p>
 704 </div>
 705 <hr>
 706 <div class="refsect2">
 707 <a name="gst-iterator-next"></a><h3>gst_iterator_next ()</h3>
 708 <pre class="programlisting"><a class="link" href="gstreamer-GstIterator.html#GstIteratorResult" title="enum GstIteratorResult"><span class="returnvalue">GstIteratorResult</span></a>   gst_iterator_next                   (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
 709                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> *elem</code></em>);</pre>
 710 <p>
 711 Get the next item from the iterator in <em class="parameter"><code>elem</code></em>.
 712 </p>
 713 <p>
 714 Only when this function returns <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-OK:CAPS"><code class="literal">GST_ITERATOR_OK</code></a>, <em class="parameter"><code>elem</code></em> will contain a valid
 715 value. For iterators that return refcounted objects, the returned object
 716 will have its refcount increased and should therefore be unreffed after
 717 usage.
 718 </p>
 719 <p>
 720 When this function returns <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-DONE:CAPS"><code class="literal">GST_ITERATOR_DONE</code></a>, no more elements can be
 721 retrieved from <em class="parameter"><code>it</code></em>.
 722 </p>
 723 <p>
 724 A return value of <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-RESYNC:CAPS"><code class="literal">GST_ITERATOR_RESYNC</code></a> indicates that the element list was
 725 concurrently updated. The user of <em class="parameter"><code>it</code></em> should call <a class="link" href="gstreamer-GstIterator.html#gst-iterator-resync" title="gst_iterator_resync ()"><code class="function">gst_iterator_resync()</code></a> to
 726 get the newly updated list.
 727 </p>
 728 <p>
 729 A return value of <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-ERROR:CAPS"><code class="literal">GST_ITERATOR_ERROR</code></a> indicates an unrecoverable fatal error.
 730 </p>
 731 <div class="variablelist"><table border="0">
 732 <col align="left" valign="top">
 733 <tbody>
 734 <tr>
 735 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 736 <td>The <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> to iterate</td>
 737 </tr>
 738 <tr>
 739 <td><p><span class="term"><em class="parameter"><code>elem</code></em> :</span></p></td>
 740 <td>pointer to hold next element</td>
 741 </tr>
 742 <tr>
 743 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 744 <td>The result of the iteration. Unref <em class="parameter"><code>elem</code></em> after usage if this
 745 is a refcounted object.
 746 MT safe.</td>
 747 </tr>
 748 </tbody>
 749 </table></div>
 750 </div>
 751 <hr>
 752 <div class="refsect2">
 753 <a name="gst-iterator-resync"></a><h3>gst_iterator_resync ()</h3>
 754 <pre class="programlisting"><span class="returnvalue">void</span>                gst_iterator_resync                 (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>);</pre>
 755 <p>
 756 Resync the iterator. this function is mostly called
 757 after <a class="link" href="gstreamer-GstIterator.html#gst-iterator-next" title="gst_iterator_next ()"><code class="function">gst_iterator_next()</code></a> returned <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-RESYNC:CAPS"><code class="literal">GST_ITERATOR_RESYNC</code></a>.
 758 </p>
 759 <p>
 760 When an iterator was pushed on <em class="parameter"><code>it</code></em>, it will automatically be popped again
 761 with this function.
 762 </p>
 763 <p>
 764 MT safe.
 765 </p>
 766 <div class="variablelist"><table border="0">
 767 <col align="left" valign="top">
 768 <tbody><tr>
 769 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 770 <td>The <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> to resync</td>
 771 </tr></tbody>
 772 </table></div>
 773 </div>
 774 <hr>
 775 <div class="refsect2">
 776 <a name="gst-iterator-free"></a><h3>gst_iterator_free ()</h3>
 777 <pre class="programlisting"><span class="returnvalue">void</span>                gst_iterator_free                   (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>);</pre>
 778 <p>
 779 Free the iterator.
 780 </p>
 781 <p>
 782 MT safe.
 783 </p>
 784 <div class="variablelist"><table border="0">
 785 <col align="left" valign="top">
 786 <tbody><tr>
 787 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 788 <td>The <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> to free</td>
 789 </tr></tbody>
 790 </table></div>
 791 </div>
 792 <hr>
 793 <div class="refsect2">
 794 <a name="gst-iterator-push"></a><h3>gst_iterator_push ()</h3>
 795 <pre class="programlisting"><span class="returnvalue">void</span>                gst_iterator_push                   (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
 796                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *other</code></em>);</pre>
 797 <p>
 798 Pushes <em class="parameter"><code>other</code></em> iterator onto <em class="parameter"><code>it</code></em>. All calls performed on <em class="parameter"><code>it</code></em> are
 799 forwarded to <em class="parameter"><code>other</code></em>. If <em class="parameter"><code>other</code></em> returns <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-DONE:CAPS"><code class="literal">GST_ITERATOR_DONE</code></a>, it is
 800 popped again and calls are handled by <em class="parameter"><code>it</code></em> again.
 801 </p>
 802 <p>
 803 This function is mainly used by objects implementing the iterator
 804 next function to recurse into substructures.
 805 </p>
 806 <p>
 807 When <a class="link" href="gstreamer-GstIterator.html#gst-iterator-resync" title="gst_iterator_resync ()"><code class="function">gst_iterator_resync()</code></a> is called on <em class="parameter"><code>it</code></em>, <em class="parameter"><code>other</code></em> will automatically be
 808 popped.
 809 </p>
 810 <p>
 811 MT safe.
 812 </p>
 813 <div class="variablelist"><table border="0">
 814 <col align="left" valign="top">
 815 <tbody>
 816 <tr>
 817 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 818 <td>The <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> to use</td>
 819 </tr>
 820 <tr>
 821 <td><p><span class="term"><em class="parameter"><code>other</code></em> :</span></p></td>
 822 <td>The <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> to push</td>
 823 </tr>
 824 </tbody>
 825 </table></div>
 826 </div>
 827 <hr>
 828 <div class="refsect2">
 829 <a name="gst-iterator-filter"></a><h3>gst_iterator_filter ()</h3>
 830 <pre class="programlisting"><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="returnvalue">GstIterator</span></a> *       gst_iterator_filter                 (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
 831                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#GCompareFunc"><span class="type">GCompareFunc</span></a> func</code></em>,
 832                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 833 <p>
 834 Create a new iterator from an existing iterator. The new iterator
 835 will only return those elements that match the given compare function <em class="parameter"><code>func</code></em>.
 836 <em class="parameter"><code>func</code></em> should return 0 for elements that should be included
 837 in the iterator.
 838 </p>
 839 <p>
 840 When this iterator is freed, <em class="parameter"><code>it</code></em> will also be freed.
 841 </p>
 842 <div class="variablelist"><table border="0">
 843 <col align="left" valign="top">
 844 <tbody>
 845 <tr>
 846 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 847 <td>The <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> to filter</td>
 848 </tr>
 849 <tr>
 850 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 851 <td>the compare function to select elements. <span class="annotation">[<acronym title="The callback is valid only during the call to the method."><span class="acronym">scope call</span></acronym>]</span>
 852 </td>
 853 </tr>
 854 <tr>
 855 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 856 <td>user data passed to the compare function. <span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span>
 857 </td>
 858 </tr>
 859 <tr>
 860 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 861 <td>a new <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a>.
 862 MT safe. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 863 </td>
 864 </tr>
 865 </tbody>
 866 </table></div>
 867 </div>
 868 <hr>
 869 <div class="refsect2">
 870 <a name="gst-iterator-fold"></a><h3>gst_iterator_fold ()</h3>
 871 <pre class="programlisting"><a class="link" href="gstreamer-GstIterator.html#GstIteratorResult" title="enum GstIteratorResult"><span class="returnvalue">GstIteratorResult</span></a>   gst_iterator_fold                   (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
 872                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIteratorFoldFunction" title="GstIteratorFoldFunction ()"><span class="type">GstIteratorFoldFunction</span></a> func</code></em>,
 873                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> *ret</code></em>,
 874                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 875 <p>
 876 Folds <em class="parameter"><code>func</code></em> over the elements of <em class="parameter"><code>iter</code></em>. That is to say, <em class="parameter"><code>func</code></em> will be called
 877 as <em class="parameter"><code>func</code></em> (object, <em class="parameter"><code>ret</code></em>, <em class="parameter"><code>user_data</code></em>) for each object in <em class="parameter"><code>it</code></em>. The normal use
 878 of this procedure is to accumulate the results of operating on the objects in
 879 <em class="parameter"><code>ret</code></em>.  If object is a refcounted object its refcount will be increased
 880 before <em class="parameter"><code>func</code></em> is called, and it should be unrefed after use in <em class="parameter"><code>func</code></em>.
 881 </p>
 882 <p>
 883 This procedure can be used (and is used internally) to implement the
 884 <a class="link" href="gstreamer-GstIterator.html#gst-iterator-foreach" title="gst_iterator_foreach ()"><code class="function">gst_iterator_foreach()</code></a> and <a class="link" href="gstreamer-GstIterator.html#gst-iterator-find-custom" title="gst_iterator_find_custom ()"><code class="function">gst_iterator_find_custom()</code></a> operations.
 885 </p>
 886 <p>
 887 The fold will proceed as long as <em class="parameter"><code>func</code></em> returns TRUE. When the iterator has no
 888 more arguments, <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-DONE:CAPS"><code class="literal">GST_ITERATOR_DONE</code></a> will be returned. If <em class="parameter"><code>func</code></em> returns FALSE,
 889 the fold will stop, and <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-OK:CAPS"><code class="literal">GST_ITERATOR_OK</code></a> will be returned. Errors or resyncs
 890 will cause fold to return <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-ERROR:CAPS"><code class="literal">GST_ITERATOR_ERROR</code></a> or <a class="link" href="gstreamer-GstIterator.html#GST-ITERATOR-RESYNC:CAPS"><code class="literal">GST_ITERATOR_RESYNC</code></a> as
 891 appropriate.
 892 </p>
 893 <p>
 894 The iterator will not be freed.
 895 </p>
 896 <div class="variablelist"><table border="0">
 897 <col align="left" valign="top">
 898 <tbody>
 899 <tr>
 900 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 901 <td>The <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> to fold over</td>
 902 </tr>
 903 <tr>
 904 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 905 <td>the fold function. <span class="annotation">[<acronym title="The callback is valid only during the call to the method."><span class="acronym">scope call</span></acronym>]</span>
 906 </td>
 907 </tr>
 908 <tr>
 909 <td><p><span class="term"><em class="parameter"><code>ret</code></em> :</span></p></td>
 910 <td>the seed value passed to the fold function</td>
 911 </tr>
 912 <tr>
 913 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 914 <td>user data passed to the fold function. <span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span>
 915 </td>
 916 </tr>
 917 <tr>
 918 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 919 <td>A <a class="link" href="gstreamer-GstIterator.html#GstIteratorResult" title="enum GstIteratorResult"><span class="type">GstIteratorResult</span></a>, as described above.
 920 MT safe.</td>
 921 </tr>
 922 </tbody>
 923 </table></div>
 924 </div>
 925 <hr>
 926 <div class="refsect2">
 927 <a name="gst-iterator-foreach"></a><h3>gst_iterator_foreach ()</h3>
 928 <pre class="programlisting"><a class="link" href="gstreamer-GstIterator.html#GstIteratorResult" title="enum GstIteratorResult"><span class="returnvalue">GstIteratorResult</span></a>   gst_iterator_foreach                (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
 929                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#GFunc"><span class="type">GFunc</span></a> func</code></em>,
 930                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 931 <p>
 932 Iterate over all element of <em class="parameter"><code>it</code></em> and call the given function <em class="parameter"><code>func</code></em> for
 933 each element.  As in <a class="link" href="gstreamer-GstIterator.html#gst-iterator-fold" title="gst_iterator_fold ()"><code class="function">gst_iterator_fold()</code></a>, the refcount of a refcounted
 934 object will be increased before <em class="parameter"><code>func</code></em> is called, and should be unrefed
 935 after use.
 936 </p>
 937 <div class="variablelist"><table border="0">
 938 <col align="left" valign="top">
 939 <tbody>
 940 <tr>
 941 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 942 <td>The <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> to iterate</td>
 943 </tr>
 944 <tr>
 945 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 946 <td>the function to call for each element. <span class="annotation">[<acronym title="The callback is valid only during the call to the method."><span class="acronym">scope call</span></acronym>]</span>
 947 </td>
 948 </tr>
 949 <tr>
 950 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 951 <td>user data passed to the function. <span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span>
 952 </td>
 953 </tr>
 954 <tr>
 955 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 956 <td>the result call to <a class="link" href="gstreamer-GstIterator.html#gst-iterator-fold" title="gst_iterator_fold ()"><code class="function">gst_iterator_fold()</code></a>. The iterator will not be
 957 freed.
 958 MT safe.</td>
 959 </tr>
 960 </tbody>
 961 </table></div>
 962 </div>
 963 <hr>
 964 <div class="refsect2">
 965 <a name="gst-iterator-find-custom"></a><h3>gst_iterator_find_custom ()</h3>
 966 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a>            gst_iterator_find_custom            (<em class="parameter"><code><a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> *it</code></em>,
 967                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#GCompareFunc"><span class="type">GCompareFunc</span></a> func</code></em>,
 968                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 969 <p>
 970 Find the first element in <em class="parameter"><code>it</code></em> that matches the compare function <em class="parameter"><code>func</code></em>.
 971 <em class="parameter"><code>func</code></em> should return 0 when the element is found.  As in <a class="link" href="gstreamer-GstIterator.html#gst-iterator-fold" title="gst_iterator_fold ()"><code class="function">gst_iterator_fold()</code></a>,
 972 the refcount of a refcounted object will be increased before <em class="parameter"><code>func</code></em> is
 973 called, and should be unrefed after use in <em class="parameter"><code>func</code></em> unless it is the matching
 974 element.
 975 </p>
 976 <p>
 977 The iterator will not be freed.
 978 </p>
 979 <p>
 980 This function will return NULL if an error happened to the iterator.
 981 </p>
 982 <div class="variablelist"><table border="0">
 983 <col align="left" valign="top">
 984 <tbody>
 985 <tr>
 986 <td><p><span class="term"><em class="parameter"><code>it</code></em> :</span></p></td>
 987 <td>The <a class="link" href="gstreamer-GstIterator.html#GstIterator" title="struct GstIterator"><span class="type">GstIterator</span></a> to iterate</td>
 988 </tr>
 989 <tr>
 990 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 991 <td>the compare function to use. <span class="annotation">[<acronym title="The callback is valid only during the call to the method."><span class="acronym">scope call</span></acronym>]</span>
 992 </td>
 993 </tr>
 994 <tr>
 995 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 996 <td>user data passed to the compare function. <span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span>
 997 </td>
 998 </tr>
 999 <tr>
1000 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1001 <td>The element in the iterator that matches the compare
1002 function or NULL when no element matched.
1003 MT safe. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
1004 </td>
1005 </tr>
1006 </tbody>
1007 </table></div>
1008 </div>
1009 </div>
1010 <div class="refsect1">
1011 <a name="gstreamer-GstIterator.see-also"></a><h2>See Also</h2>
1012 <a class="link" href="GstElement.html" title="GstElement"><span class="type">GstElement</span></a>, <a class="link" href="GstBin.html" title="GstBin"><span class="type">GstBin</span></a>
1013 </div>
1014 </div>
1015 <div class="footer">
1016 <hr>
1017           Generated by GTK-Doc V1.18</div>
1018 </body>
1019 </html>