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

— Function: gst-iterator-new (size unsigned-int) (type <gtype>) (lock <g-mutex*>) (next <gst-iterator-next-function>) (item <gst-iterator-item-function>) (resync <gst-iterator-resync-function>) (free <gst-iterator-free-function>)   (ret <gst-iterator*>) (master_cookie unsigned-int32)

Create a new iterator. This function is mainly used for objects implementing the next/resync/free function to iterate a data structure.

For each item retrieved, the item function is called with the lock held. The free function is called when the iterator is freed.

size

the size of the iterator structure

type

<g-type> of children

lock

pointer to a <g-mutex>.

master-cookie

pointer to a guint32 to protect the iterated object.

next

function to get next item

item

function to call on each item retrieved

resync

function to resync the iterator

free

function to free the iterator

ret

the new <gst-iterator>. MT safe.

— Function: gst-iterator-new-list (type <gtype>) (lock <g-mutex*>) (list <g-list**>) (owner <gpointer>) (item <gst-iterator-item-function>) (free <gst-iterator-dispose-function>)   (ret <gst-iterator*>) (master_cookie unsigned-int32)

Create a new iterator designed for iterating list.

type

<g-type> of elements

lock

pointer to a <g-mutex> protecting the list.

master-cookie

pointer to a guint32 to protect the list.

list

pointer to the list

owner

object owning the list

item

function to call for each item

free

function to call when the iterator is freed

ret

the new <gst-iterator> for list. MT safe.

— Function: gst-iterator-next (self <gst-iterator*>) (elem <gpointer*>)   (ret <gst-iterator-result>)

Get the next item from the iterator. For iterators that return refcounted objects, the returned object will have its refcount increased and should therefore be unreffed after usage.

it

The <gst-iterator> to iterate

elem

pointer to hold next element

ret

The result of the iteration. Unref after usage if this is a refcounted object. MT safe.

— Function: gst-iterator-resync (self <gst-iterator*>)

Resync the iterator. this function is mostly called after gst-iterator-next returned ‘GST_ITERATOR_RESYNC’.

MT safe.

it

The <gst-iterator> to resync

— Function: gst-iterator-push (self <gst-iterator*>) (other <gst-iterator*>)

Pushes other iterator onto it. All calls performed on it are forwarded tot other. If other returns <gst-iterator-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.

MT safe.

it

The <gst-iterator> to use

other

The <gst-iterator> to push

— Function: gst-iterator-filter (self <gst-iterator*>) (func <g-compare-func>) (user_data <gpointer>)   (ret <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. func should return 0 for elements that should be included in the iterator.

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

it

The <gst-iterator> to filter

func

the compare function to select elements

user-data

user data passed to the compare function

ret

a new <gst-iterator>. MT safe.

— Function: gst-iterator-fold (self <gst-iterator*>) (func <gst-iterator-fold-function>) (ret <gvalue>) (user_data <gpointer>)   (ret <gst-iterator-result>)

Folds func over the elements of iter. That is to say, proc will be called as proc (object, ret, user-data) for each object in iter. 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 foreach and find_custom operations.

The fold will proceed as long as func returns TRUE. When the iterator has no more arguments, <gst-iterator-done> will be returned. If func returns FALSE, the fold will stop, and <gst-iterator-ok> will be returned. Errors or resyncs will cause fold to return <gst-iterator-error> or <gst-iterator-resync> as appropriate.

The iterator will not be freed.

it

The <gst-iterator> to fold over

func

the fold function

ret

the seed value passed to the fold function

user-data

user data passed to the fold function

ret

A <gst-iterator-result>, as described above. MT safe.

— Function: gst-iterator-foreach (self <gst-iterator*>) (func <g-func>) (user_data <gpointer>)   (ret <gst-iterator-result>)

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

it

The <gst-iterator> to iterate

func

the function to call for each element.

user-data

user data passed to the function

ret

the result call to gst-iterator-fold. The iterator will not be freed. MT safe.

— Function: gst-iterator-find-custom (self <gst-iterator*>) (func <g-compare-func>) (user_data <gpointer>)   (ret <gpointer>)

Find the first element in it that matches the compare function func. func should return 0 when the element is found.

The iterator will not be freed.

This function will return NULL if an error or resync happened to the iterator.

it

The <gst-iterator> to iterate

func

the compare function to use

user-data

user data passed to the compare function

ret

The element in the iterator that matches the compare function or NULL when no element matched. MT safe.