GI.Gst.Structs.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, 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, &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);

Exported types

newtype Iterator

Memory-managed wrapper type.

Constructors

Iterator (ManagedPtr Iterator)

Instances

BoxedObject Iterator

Defined in GI.Gst.Structs.Iterator

Methods

boxedType :: Iterator -> IO GType

tag ~ AttrSet => Constructible Iterator tag

Defined in GI.Gst.Structs.Iterator

Methods

new :: MonadIO m => (ManagedPtr Iterator -> Iterator) -> [AttrOp Iterator tag] -> m Iterator

newZeroIterator :: MonadIO m => m Iterator

Construct a Iterator struct initialized to zero.

noIterator :: Maybe Iterator

A convenience alias for Nothing :: Maybe Iterator.

Methods

copy

iteratorCopy

Arguments

:: (HasCallStack, MonadIO m)

=> Iterator

it: a Iterator

-> m Iterator

Returns: a new copy of it.

Copy the iterator and its state.

filter

iteratorFilter

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

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

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

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

Arguments

:: (HasCallStack, MonadIO m)

=> Iterator

it: The Iterator to free

-> m ()

Free the iterator.

MT safe.

newSingle

iteratorNewSingle

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.

next

iteratorNext

Arguments

:: (HasCallStack, MonadIO m)

=> Iterator

it: The Iterator to iterate

-> m (IteratorResult, GValue)

Returns: The result of the iteration. Unset elem after usage.

MT safe.

Get the next item from the iterator in elem.

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

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.

resync

iteratorResync

Arguments

:: (HasCallStack, MonadIO m)

=> Iterator

it: The Iterator to resync

-> m ()

Resync the iterator. this function is mostly called after iteratorNext returned IteratorResultResync.

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

MT safe.

Properties

cookie

The cookie; the value of the master_cookie when this iterator was created.

getIteratorCookie :: MonadIO m => Iterator -> m Word32

Get the value of the “cookie” field. When overloading is enabled, this is equivalent to

get iterator #cookie

setIteratorCookie :: MonadIO m => Iterator -> Word32 -> m ()

Set the value of the “cookie” field. When overloading is enabled, this is equivalent to

set iterator [ #cookie := value ]

copy

The function to copy the iterator

clearIteratorCopy :: MonadIO m => Iterator -> m ()

Set the value of the “copy” field to Nothing. When overloading is enabled, this is equivalent to

clear #copy

getIteratorCopy :: MonadIO m => Iterator -> m (Maybe IteratorCopyFunction)

Get the value of the “copy” field. When overloading is enabled, this is equivalent to

get iterator #copy

setIteratorCopy :: MonadIO m => Iterator -> FunPtr C_IteratorCopyFunction -> m ()

Set the value of the “copy” field. When overloading is enabled, this is equivalent to

set iterator [ #copy := value ]

free

The function to call when the iterator is freed

clearIteratorFree :: MonadIO m => Iterator -> m ()

Set the value of the “free” field to Nothing. When overloading is enabled, this is equivalent to

clear #free

getIteratorFree :: MonadIO m => Iterator -> m (Maybe IteratorFreeFunction)

Get the value of the “free” field. When overloading is enabled, this is equivalent to

get iterator #free

setIteratorFree :: MonadIO m => Iterator -> FunPtr C_IteratorFreeFunction -> m ()

Set the value of the “free” field. When overloading is enabled, this is equivalent to

set iterator [ #free := value ]

item

The function to be called for each item retrieved

clearIteratorItem :: MonadIO m => Iterator -> m ()

Set the value of the “item” field to Nothing. When overloading is enabled, this is equivalent to

clear #item

getIteratorItem :: MonadIO m => Iterator -> m (Maybe IteratorItemFunction)

Get the value of the “item” field. When overloading is enabled, this is equivalent to

get iterator #item

setIteratorItem :: MonadIO m => Iterator -> FunPtr C_IteratorItemFunction -> m ()

Set the value of the “item” field. When overloading is enabled, this is equivalent to

set iterator [ #item := value ]

lock

The lock protecting the data structure and the cookie.

clearIteratorLock :: MonadIO m => Iterator -> m ()

Set the value of the “lock” field to Nothing. When overloading is enabled, this is equivalent to

clear #lock

getIteratorLock :: MonadIO m => Iterator -> m (Maybe Mutex)

Get the value of the “lock” field. When overloading is enabled, this is equivalent to

get iterator #lock

setIteratorLock :: MonadIO m => Iterator -> Ptr Mutex -> m ()

Set the value of the “lock” field. When overloading is enabled, this is equivalent to

set iterator [ #lock := value ]

masterCookie

A pointer to the master cookie.

getIteratorMasterCookie :: MonadIO m => Iterator -> m Word32

Get the value of the “master_cookie” field. When overloading is enabled, this is equivalent to

get iterator #masterCookie

setIteratorMasterCookie :: MonadIO m => Iterator -> Word32 -> m ()

Set the value of the “master_cookie” field. When overloading is enabled, this is equivalent to

set iterator [ #masterCookie := value ]

next

The function to get the next item in the iterator

clearIteratorNext :: MonadIO m => Iterator -> m ()

Set the value of the “next” field to Nothing. When overloading is enabled, this is equivalent to

clear #next

getIteratorNext :: MonadIO m => Iterator -> m (Maybe IteratorNextFunction)

Get the value of the “next” field. When overloading is enabled, this is equivalent to

get iterator #next

setIteratorNext :: MonadIO m => Iterator -> FunPtr C_IteratorNextFunction -> m ()

Set the value of the “next” field. When overloading is enabled, this is equivalent to

set iterator [ #next := value ]

pushed

The iterator that is currently pushed with iteratorPush

clearIteratorPushed :: MonadIO m => Iterator -> m ()

Set the value of the “pushed” field to Nothing. When overloading is enabled, this is equivalent to

clear #pushed

getIteratorPushed :: MonadIO m => Iterator -> m (Maybe Iterator)

Get the value of the “pushed” field. When overloading is enabled, this is equivalent to

get iterator #pushed

setIteratorPushed :: MonadIO m => Iterator -> Ptr Iterator -> m ()

Set the value of the “pushed” field. When overloading is enabled, this is equivalent to

set iterator [ #pushed := value ]

resync

The function to call when a resync is needed.

clearIteratorResync :: MonadIO m => Iterator -> m ()

Set the value of the “resync” field to Nothing. When overloading is enabled, this is equivalent to

clear #resync

getIteratorResync :: MonadIO m => Iterator -> m (Maybe IteratorResyncFunction)

Get the value of the “resync” field. When overloading is enabled, this is equivalent to

get iterator #resync

setIteratorResync :: MonadIO m => Iterator -> FunPtr C_IteratorResyncFunction -> m ()

Set the value of the “resync” field. When overloading is enabled, this is equivalent to

set iterator [ #resync := value ]

size

the size of the iterator

getIteratorSize :: MonadIO m => Iterator -> m Word32

Get the value of the “size” field. When overloading is enabled, this is equivalent to

get iterator #size

setIteratorSize :: MonadIO m => Iterator -> Word32 -> m ()

Set the value of the “size” field. When overloading is enabled, this is equivalent to

set iterator [ #size := value ]

type

The type of the object that this iterator will return

getIteratorType :: MonadIO m => Iterator -> m GType

Get the value of the “type” field. When overloading is enabled, this is equivalent to

get iterator #type

setIteratorType :: MonadIO m => Iterator -> GType -> m ()

Set the value of the “type” field. When overloading is enabled, this is equivalent to

set iterator [ #type := value ]