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:
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:
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:
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:
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:
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.