Copyright	Will Thompson Iñaki García Etxebarria and Jonas Platte
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell	None
Language	Haskell2010

GI.Gst.Structs.Iterator

Contents

Exported types
Methods
Properties

Description

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, valueGetObject), 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:

C code

 GstIterator *it = _get_iterator(object);
 GValue item = G_VALUE_INIT;
 done = FALSE;
 while (!done) {
   switch (gst_iterator_next (it, &amp;item)) {
     case GST_ITERATOR_OK:
       ...get/use/change item here...
       g_value_reset (&amp;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 (&amp;item);
 gst_iterator_free (it);

Synopsis

Exported types

newtype Iterator Source #

Constructors

Iterator (ManagedPtr Iterator)

Instances

BoxedObject Iterator Source #
Methods boxedType :: Iterator -> IO GType #
(~) AttrOpTag tag AttrSet => Constructible Iterator tag Source #
Methods new :: MonadIO m => (ManagedPtr Iterator -> Iterator) -> [AttrOp Iterator tag] -> m Iterator #

newZeroIterator :: MonadIO m => m Iterator Source #

Construct a Iterator struct initialized to zero.

noIterator :: Maybe Iterator Source #

Methods

copy

iteratorCopy Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Iterator	`it`: a `Iterator`
-> m Iterator	Returns: a new copy of `it`.

Copy the iterator and its state.

filter

iteratorFilter Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Iterator	`it`: The `Iterator` to filter
-> CompareFunc	`func`: the compare function to select elements
-> GValue	`userData`: user data passed to the compare function
-> m Iterator	Returns: a new `Iterator`. MT safe.

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 Value of the current iterator element and the second parameter is userData. func should return 0 for elements that should be included in the filtered iterator.

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

findCustom

iteratorFindCustom Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Iterator	`it`: The `Iterator` to iterate
-> CompareFunc	`func`: the compare function to use
-> m (Bool, GValue)	Returns: Returns `True` if the element was found, else `False`. 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 userData. 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

iteratorFold Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Iterator	`it`: The `Iterator` to fold over
-> IteratorFoldFunction	`func`: the fold function
-> GValue	`ret`: the seed value passed to the fold function
-> m IteratorResult	Returns: A `IteratorResult`, as described above. MT safe.

Folds func over the elements of iter. That is to say, func will be called as func (object, ret, userData) for each object in it. 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 iteratorForeach and iteratorFindCustom operations.

The fold will proceed as long as func returns True. When the iterator has no more arguments, IteratorResultDone will be returned. If func returns False, the fold will stop, and IteratorResultOk will be returned. Errors or resyncs will cause fold to return IteratorResultError or IteratorResultResync as appropriate.

The iterator will not be freed.

foreach

iteratorForeach Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Iterator	`it`: The `Iterator` to iterate
-> IteratorForeachFunction	`func`: the function to call for each element.
-> m IteratorResult	Returns: the result call to `iteratorFold`. The iterator will not be freed. MT safe.

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

free

iteratorFree Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Iterator	`it`: The `Iterator` to free
-> m ()

Free the iterator.

MT safe.

newSingle

iteratorNewSingle Source #

Arguments

:: (HasCallStack, MonadIO m)
=> GType	`type`: `GType` of the passed object
-> GValue	`object`: object that this iterator should return
-> m Iterator	Returns: the new `Iterator` for `object`.

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

Only when this function returns IteratorResultOk, elem will contain a valid value. elem must have been initialized to the type of the iterator or initialized to zeroes with valueUnset. The caller is responsible for unsetting or resetting elem with valueUnset or valueReset after usage.

When this function returns IteratorResultDone, no more elements can be retrieved from it.

A return value of IteratorResultResync indicates that the element list was concurrently updated. The user of it should call iteratorResync to get the newly updated list.

A return value of IteratorResultError indicates an unrecoverable fatal error.

push

iteratorPush Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Iterator	`it`: The `Iterator` to use
-> Iterator	`other`: The `Iterator` to push
-> m ()

Pushes other iterator onto it. All calls performed on it are forwarded to other. If other returns IteratorResultDone, 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 iteratorResync is called on it, other will automatically be popped.

MT safe.