Gst.Iterator¶

Fields¶

Name	Type	Access	Description
cookie	`int`	r/w	The cookie; the value of the master_cookie when this iterator was created.
copy	`Gst.IteratorCopyFunction`	r/w	The function to copy the iterator
free	`Gst.IteratorFreeFunction`	r/w	The function to call when the iterator is freed
item	`Gst.IteratorItemFunction`	r/w	The function to be called for each item retrieved
lock	`GLib.Mutex`	r/w	The lock protecting the data structure and the cookie.
master_cookie	`int`	r/w	A pointer to the master cookie.
next	`Gst.IteratorNextFunction`	r/w	The function to get the next item in the iterator
pushed	`Gst.Iterator`	r/w	The iterator that is currently pushed with `Gst.Iterator.push`()
resync	`Gst.IteratorResyncFunction`	r/w	The function to call when a resync is needed.
size	`int`	r/w	the size of the iterator
type	`GObject.GType`	r/w	The type of the object that this iterator will return

Methods¶

class	`new_single` (type, object)
	`filter` (func, user_data)
	`find_custom` (func, *user_data)
	`fold` (func, ret, *user_data)
	`foreach` (func, *user_data)
	`push` (other)

Details¶

class Gst.Iterator¶

A Gst.Iterator is used to retrieve multiple objects from another object in a threadsafe way.

Various GStreamer objects provide access to their internal structures using an iterator.

Note that if calling a Gst.Iterator function results in your code receiving a refcounted object (with, say, GObject.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:

GstIterator *it = _get_iterator(object);
GValue item = G_VALUE_INIT;
done = FALSE;
while (!done) {
  switch (gst_iterator_next (it, &item)) {
    case GST_ITERATOR_OK:
      ...get/use/change item here...
      g_value_reset (&item);
      break;
    case GST_ITERATOR_RESYNC:
      ...rollback changes to items...
      gst_iterator_resync (it);
      break;
    case GST_ITERATOR_ERROR:
      ...wrong parameters were given...
      done = TRUE;
      break;
    case GST_ITERATOR_DONE:
      done = TRUE;
      break;
  }
}
g_value_unset (&item);
gst_iterator_free (it);

classmethod new_single(type, object)[source]¶

Parameters:

type (GObject.GType) – GObject.GType of the passed object
object (GObject.Value) – object that this iterator should return

Returns:

the new Gst.Iterator for object.

Return type:

Gst.Iterator

This Gst.Iterator is a convenient iterator for the common case where a Gst.Iterator needs to be returned but only a single object has to be considered. This happens often for the Gst.PadIterIntLinkFunction.

filter(func, user_data)[source]¶

Parameters:

func (GLib.CompareFunc) – the compare function to select elements
user_data (GObject.Value) – user data passed to the compare function

Returns:

a new Gst.Iterator.

MT safe.

Return type:

Gst.Iterator

Create a new iterator from an existing iterator. The new iterator will only return those elements that match the given compare function func. The first parameter that is passed to func is the GObject.Value of the current iterator element and the second parameter is user_data. func should return 0 for elements that should be included in the filtered iterator.

When this iterator is freed, self will also be freed.

find_custom(func, *user_data)[source]¶

Parameters:

func (GLib.CompareFunc) – the compare function to use
user_data (object or None) – user data passed to the compare function

Returns:

Returns True if the element was found, else False.

MT safe.

elem:: pointer to a GObject.Value where to store the result

Return type:

(bool, elem: GObject.Value)

Find the first element in self that matches the compare function func. func should return 0 when the element is found. The first parameter to func will be the current element of the iterator and the second parameter will be user_data. The result will be stored in elem if a result is found.

The iterator will not be freed.

This function will return False if an error happened to the iterator or if the element wasn’t found.

fold(func, ret, *user_data)[source]¶

Parameters:

func (Gst.IteratorFoldFunction) – the fold function
ret (GObject.Value) – the seed value passed to the fold function
user_data (object or None) – user data passed to the fold function

Returns:

A Gst.IteratorResult, as described above.

MT safe.

Return type:

Gst.IteratorResult

Folds func over the elements of iter. That is to say, func will be called as func (object, ret, user_data) for each object in self. The normal use of this procedure is to accumulate the results of operating on the objects in ret.

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.IteratorResult.DONE will be returned. If func returns False, the fold will stop, and Gst.IteratorResult.OK will be returned. Errors or resyncs will cause fold to return Gst.IteratorResult.ERROR or Gst.IteratorResult.RESYNC as appropriate.

The iterator will not be freed.

foreach(func, *user_data)[source]¶

Parameters:

func (Gst.IteratorForeachFunction) – the function to call for each element.
user_data (object or None) – user data passed to the function

Returns:

the result call to Gst.Iterator.fold(). The iterator will not be freed.

MT safe.

Return type:

Gst.IteratorResult

Iterate over all element of self and call the given function func for each element.

push(other)[source]¶

Parameters:: other (Gst.Iterator) – The Gst.Iterator to push

Pushes other iterator onto self. All calls performed on self are forwarded to other. If other returns Gst.IteratorResult.DONE, it is popped again and calls are handled by self again.

This function is mainly used by objects implementing the iterator next function to recurse into substructures.

When Gst.Iterator.resync() is called on self, other will automatically be popped.

MT safe.