1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gstreamer.Iterator;
26 
27 private import glib.ConstructionException;
28 private import glib.ListG;
29 private import glib.MemorySlice;
30 private import glib.Mutex;
31 private import gobject.ObjectG;
32 private import gobject.Value;
33 private import gstreamer.c.functions;
34 public  import gstreamer.c.types;
35 public  import gstreamerc.gstreamertypes;
36 private import gtkd.Loader;
37 
38 
39 /**
40  * A GstIterator is used to retrieve multiple objects from another object in
41  * a threadsafe way.
42  * 
43  * Various GStreamer objects provide access to their internal structures using
44  * an iterator.
45  * 
46  * Note that if calling a GstIterator function results in your code receiving
47  * a refcounted object (with, say, g_value_get_object()), the refcount for that
48  * object will not be increased. Your code is responsible for taking a reference
49  * if it wants to continue using it later.
50  * 
51  * The basic use pattern of an iterator is as follows:
52  * |[<!-- language="C" -->
53  * GstIterator *it = _get_iterator(object);
54  * GValue item = G_VALUE_INIT;
55  * done = FALSE;
56  * while (!done) {
57  * switch (gst_iterator_next (it, &amp;item)) {
58  * case GST_ITERATOR_OK:
59  * ...get/use/change item here...
60  * g_value_reset (&amp;item);
61  * break;
62  * case GST_ITERATOR_RESYNC:
63  * ...rollback changes to items...
64  * gst_iterator_resync (it);
65  * break;
66  * case GST_ITERATOR_ERROR:
67  * ...wrong parameters were given...
68  * done = TRUE;
69  * break;
70  * case GST_ITERATOR_DONE:
71  * done = TRUE;
72  * break;
73  * }
74  * }
75  * g_value_unset (&amp;item);
76  * gst_iterator_free (it);
77  * ]|
78  */
79 public class Iterator
80 {
81 	/** the main Gtk struct */
82 	protected GstIterator* gstIterator;
83 	protected bool ownedRef;
84 
85 	/** Get the main Gtk struct */
86 	public GstIterator* getIteratorStruct(bool transferOwnership = false)
87 	{
88 		if (transferOwnership)
89 			ownedRef = false;
90 		return gstIterator;
91 	}
92 
93 	/** the main Gtk struct as a void* */
94 	protected void* getStruct()
95 	{
96 		return cast(void*)gstIterator;
97 	}
98 
99 	/**
100 	 * Sets our main struct and passes it to the parent class.
101 	 */
102 	public this (GstIterator* gstIterator, bool ownedRef = false)
103 	{
104 		this.gstIterator = gstIterator;
105 		this.ownedRef = ownedRef;
106 	}
107 
108 	~this ()
109 	{
110 		if ( Linker.isLoaded(LIBRARY_GSTREAMER) && ownedRef )
111 			gst_iterator_free(gstIterator);
112 	}
113 
114 
115 	/** */
116 	public static GType getType()
117 	{
118 		return gst_iterator_get_type();
119 	}
120 
121 	/**
122 	 * Create a new iterator. This function is mainly used for objects
123 	 * implementing the next/resync/free function to iterate a data structure.
124 	 *
125 	 * For each item retrieved, the @item function is called with the lock
126 	 * held. The @free function is called when the iterator is freed.
127 	 *
128 	 * Params:
129 	 *     size = the size of the iterator structure
130 	 *     type = #GType of children
131 	 *     lock = pointer to a #GMutex.
132 	 *     masterCookie = pointer to a guint32 that is changed when the items in the
133 	 *         iterator changed.
134 	 *     copy = copy function
135 	 *     next = function to get next item
136 	 *     item = function to call on each item retrieved
137 	 *     resync = function to resync the iterator
138 	 *     free = function to free the iterator
139 	 *
140 	 * Returns: the new #GstIterator.
141 	 *
142 	 *     MT safe.
143 	 *
144 	 * Throws: ConstructionException GTK+ fails to create the object.
145 	 */
146 	public this(uint size, GType type, Mutex lock, uint* masterCookie, GstIteratorCopyFunction copy, GstIteratorNextFunction next, GstIteratorItemFunction item, GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
147 	{
148 		auto p = gst_iterator_new(size, type, (lock is null) ? null : lock.getMutexStruct(), masterCookie, copy, next, item, resync, free);
149 
150 		if(p is null)
151 		{
152 			throw new ConstructionException("null returned by new");
153 		}
154 
155 		this(cast(GstIterator*) p);
156 	}
157 
158 	/**
159 	 * Create a new iterator designed for iterating @list.
160 	 *
161 	 * The list you iterate is usually part of a data structure @owner and is
162 	 * protected with @lock.
163 	 *
164 	 * The iterator will use @lock to retrieve the next item of the list and it
165 	 * will then call the @item function before releasing @lock again.
166 	 *
167 	 * When a concurrent update to the list is performed, usually by @owner while
168 	 * holding @lock, @master_cookie will be updated. The iterator implementation
169 	 * will notice the update of the cookie and will return %GST_ITERATOR_RESYNC to
170 	 * the user of the iterator in the next call to gst_iterator_next().
171 	 *
172 	 * Params:
173 	 *     type = #GType of elements
174 	 *     lock = pointer to a #GMutex protecting the list.
175 	 *     masterCookie = pointer to a guint32 that is incremented when the list
176 	 *         is changed.
177 	 *     list = pointer to the list
178 	 *     owner = object owning the list
179 	 *     item = function to call on each item retrieved
180 	 *
181 	 * Returns: the new #GstIterator for @list.
182 	 *
183 	 *     MT safe.
184 	 *
185 	 * Throws: ConstructionException GTK+ fails to create the object.
186 	 */
187 	public this(GType type, Mutex lock, uint* masterCookie, ref ListG list, ObjectG owner, GstIteratorItemFunction item)
188 	{
189 		GList* outlist = list.getListGStruct();
190 
191 		auto p = gst_iterator_new_list(type, (lock is null) ? null : lock.getMutexStruct(), masterCookie, &outlist, (owner is null) ? null : owner.getObjectGStruct(), item);
192 
193 		if(p is null)
194 		{
195 			throw new ConstructionException("null returned by new_list");
196 		}
197 
198 		list = new ListG(outlist);
199 
200 		this(cast(GstIterator*) p);
201 	}
202 
203 	/**
204 	 * This #GstIterator is a convenient iterator for the common
205 	 * case where a #GstIterator needs to be returned but only
206 	 * a single object has to be considered. This happens often
207 	 * for the #GstPadIterIntLinkFunction.
208 	 *
209 	 * Params:
210 	 *     type = #GType of the passed object
211 	 *     object = object that this iterator should return
212 	 *
213 	 * Returns: the new #GstIterator for @object.
214 	 *
215 	 * Throws: ConstructionException GTK+ fails to create the object.
216 	 */
217 	public this(GType type, Value object)
218 	{
219 		auto p = gst_iterator_new_single(type, (object is null) ? null : object.getValueStruct());
220 
221 		if(p is null)
222 		{
223 			throw new ConstructionException("null returned by new_single");
224 		}
225 
226 		this(cast(GstIterator*) p);
227 	}
228 
229 	/**
230 	 * Copy the iterator and its state.
231 	 *
232 	 * Returns: a new copy of @it.
233 	 */
234 	public Iterator copy()
235 	{
236 		auto p = gst_iterator_copy(gstIterator);
237 
238 		if(p is null)
239 		{
240 			return null;
241 		}
242 
243 		return ObjectG.getDObject!(Iterator)(cast(GstIterator*) p, true);
244 	}
245 
246 	/**
247 	 * Create a new iterator from an existing iterator. The new iterator
248 	 * will only return those elements that match the given compare function @func.
249 	 * The first parameter that is passed to @func is the #GValue of the current
250 	 * iterator element and the second parameter is @user_data. @func should
251 	 * return 0 for elements that should be included in the filtered iterator.
252 	 *
253 	 * When this iterator is freed, @it will also be freed.
254 	 *
255 	 * Params:
256 	 *     func = the compare function to select elements
257 	 *     userData = user data passed to the compare function
258 	 *
259 	 * Returns: a new #GstIterator.
260 	 *
261 	 *     MT safe.
262 	 */
263 	public Iterator filter(GCompareFunc func, Value userData)
264 	{
265 		auto p = gst_iterator_filter(gstIterator, func, (userData is null) ? null : userData.getValueStruct());
266 
267 		if(p is null)
268 		{
269 			return null;
270 		}
271 
272 		return ObjectG.getDObject!(Iterator)(cast(GstIterator*) p, true);
273 	}
274 
275 	/**
276 	 * Find the first element in @it that matches the compare function @func.
277 	 * @func should return 0 when the element is found. The first parameter
278 	 * to @func will be the current element of the iterator and the
279 	 * second parameter will be @user_data.
280 	 * The result will be stored in @elem if a result is found.
281 	 *
282 	 * The iterator will not be freed.
283 	 *
284 	 * This function will return %FALSE if an error happened to the iterator
285 	 * or if the element wasn't found.
286 	 *
287 	 * Params:
288 	 *     func = the compare function to use
289 	 *     elem = pointer to a #GValue where to store the result
290 	 *     userData = user data passed to the compare function
291 	 *
292 	 * Returns: Returns %TRUE if the element was found, else %FALSE.
293 	 *
294 	 *     MT safe.
295 	 */
296 	public bool findCustom(GCompareFunc func, out Value elem, void* userData)
297 	{
298 		GValue* outelem = sliceNew!GValue();
299 
300 		auto p = gst_iterator_find_custom(gstIterator, func, outelem, userData) != 0;
301 
302 		elem = ObjectG.getDObject!(Value)(outelem, true);
303 
304 		return p;
305 	}
306 
307 	/**
308 	 * Folds @func over the elements of @iter. That is to say, @func will be called
309 	 * as @func (object, @ret, @user_data) for each object in @it. The normal use
310 	 * of this procedure is to accumulate the results of operating on the objects in
311 	 * @ret.
312 	 *
313 	 * This procedure can be used (and is used internally) to implement the
314 	 * gst_iterator_foreach() and gst_iterator_find_custom() operations.
315 	 *
316 	 * The fold will proceed as long as @func returns %TRUE. When the iterator has no
317 	 * more arguments, %GST_ITERATOR_DONE will be returned. If @func returns %FALSE,
318 	 * the fold will stop, and %GST_ITERATOR_OK will be returned. Errors or resyncs
319 	 * will cause fold to return %GST_ITERATOR_ERROR or %GST_ITERATOR_RESYNC as
320 	 * appropriate.
321 	 *
322 	 * The iterator will not be freed.
323 	 *
324 	 * Params:
325 	 *     func = the fold function
326 	 *     ret = the seed value passed to the fold function
327 	 *     userData = user data passed to the fold function
328 	 *
329 	 * Returns: A #GstIteratorResult, as described above.
330 	 *
331 	 *     MT safe.
332 	 */
333 	public GstIteratorResult fold(GstIteratorFoldFunction func, Value ret, void* userData)
334 	{
335 		return gst_iterator_fold(gstIterator, func, (ret is null) ? null : ret.getValueStruct(), userData);
336 	}
337 
338 	/**
339 	 * Iterate over all element of @it and call the given function @func for
340 	 * each element.
341 	 *
342 	 * Params:
343 	 *     func = the function to call for each element.
344 	 *     userData = user data passed to the function
345 	 *
346 	 * Returns: the result call to gst_iterator_fold(). The iterator will not be
347 	 *     freed.
348 	 *
349 	 *     MT safe.
350 	 */
351 	public GstIteratorResult foreac(GstIteratorForeachFunction func, void* userData)
352 	{
353 		return gst_iterator_foreach(gstIterator, func, userData);
354 	}
355 
356 	/**
357 	 * Free the iterator.
358 	 *
359 	 * MT safe.
360 	 */
361 	public void free()
362 	{
363 		gst_iterator_free(gstIterator);
364 		ownedRef = false;
365 	}
366 
367 	/**
368 	 * Get the next item from the iterator in @elem.
369 	 *
370 	 * Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid
371 	 * value. @elem must have been initialized to the type of the iterator or
372 	 * initialized to zeroes with g_value_unset(). The caller is responsible for
373 	 * unsetting or resetting @elem with g_value_unset() or g_value_reset()
374 	 * after usage.
375 	 *
376 	 * When this function returns %GST_ITERATOR_DONE, no more elements can be
377 	 * retrieved from @it.
378 	 *
379 	 * A return value of %GST_ITERATOR_RESYNC indicates that the element list was
380 	 * concurrently updated. The user of @it should call gst_iterator_resync() to
381 	 * get the newly updated list.
382 	 *
383 	 * A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error.
384 	 *
385 	 * Params:
386 	 *     elem = pointer to hold next element
387 	 *
388 	 * Returns: The result of the iteration. Unset @elem after usage.
389 	 *
390 	 *     MT safe.
391 	 */
392 	public GstIteratorResult next(out Value elem)
393 	{
394 		GValue* outelem = sliceNew!GValue();
395 
396 		auto p = gst_iterator_next(gstIterator, outelem);
397 
398 		elem = ObjectG.getDObject!(Value)(outelem, true);
399 
400 		return p;
401 	}
402 
403 	/**
404 	 * Pushes @other iterator onto @it. All calls performed on @it are
405 	 * forwarded to @other. If @other returns %GST_ITERATOR_DONE, it is
406 	 * popped again and calls are handled by @it again.
407 	 *
408 	 * This function is mainly used by objects implementing the iterator
409 	 * next function to recurse into substructures.
410 	 *
411 	 * When gst_iterator_resync() is called on @it, @other will automatically be
412 	 * popped.
413 	 *
414 	 * MT safe.
415 	 *
416 	 * Params:
417 	 *     other = The #GstIterator to push
418 	 */
419 	public void push(Iterator other)
420 	{
421 		gst_iterator_push(gstIterator, (other is null) ? null : other.getIteratorStruct());
422 	}
423 
424 	/**
425 	 * Resync the iterator. this function is mostly called
426 	 * after gst_iterator_next() returned %GST_ITERATOR_RESYNC.
427 	 *
428 	 * When an iterator was pushed on @it, it will automatically be popped again
429 	 * with this function.
430 	 *
431 	 * MT safe.
432 	 */
433 	public void resync()
434 	{
435 		gst_iterator_resync(gstIterator);
436 	}
437 }