Class (GI Struct)

Gst-1.0 ▶ Gst ▶ Iterator

A GstIterator 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 GstIterator function results in your code receiving a refcounted object (with, say, g_value_get_object()), the refcount for that object will not be increased. Your code is responsible for taking a reference if it wants to continue using it later.

The basic use pattern of an iterator is as follows:

  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);
Index

Constructors

constructor

Properties

cookie item master_cookie size type $gtype

Methods

copy filter find_custom fold foreach free next push resync new_single

Constructors

Properties

cookie: number
item: IteratorItemFunction
master_cookie: number
size: number
type: GType
$gtype: GType<Iterator>

Methods

  • 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, it will also be freed.

    Parameters

    • func: CompareFunc

      the compare function to select elements

    • user_data: any

      user data passed to the compare function

    Returns Iterator

    a new Gst.Iterator. MT safe.

  • Find the first element in it 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.

    Parameters

    Returns [boolean, unknown]

    Returns true if the element was found, else false. MT safe.

  • Get the next item from the iterator in elem.

    Only when this function returns Gst.IteratorResult.OK, elem will contain a valid value. elem must have been initialized to the type of the iterator or initialized to zeroes with g_value_unset(). The caller is responsible for unsetting or resetting elem with g_value_unset() or g_value_reset() after usage.

    When this function returns Gst.IteratorResult.DONE, no more elements can be retrieved from it.

    A return value of Gst.IteratorResult.RESYNC indicates that the element list was concurrently updated. The user of it should call gst_iterator_resync() to get the newly updated list.

    A return value of Gst.IteratorResult.ERROR indicates an unrecoverable fatal error.

    Returns [Gst.IteratorResult, unknown]

    The result of the iteration. Unset elem after usage. MT safe.

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

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

    When gst_iterator_resync() is called on it, other will automatically be popped.

    MT safe.

    Parameters

    Returns void

  • Resync the iterator. this function is mostly called after gst_iterator_next() returned Gst.IteratorResult.RESYNC.

    When an iterator was pushed on it, it will automatically be popped again with this function.

    MT safe.

    Returns void