GI.Gst.Structs.Structure

A Structure is a collection of key/value pairs. The keys are expressed as GQuarks and the values can be of any GType.

In addition to the key/value pairs, a Structure also has a name. The name starts with a letter and can be filled by letters, numbers and any of "/-_.:".

Structure is used by various GStreamer subsystems to store information in a flexible and extensible way. A Structure does not have a refcount because it usually is part of a higher level object such as Caps, Message, Event, Query. It provides a means to enforce mutability using the refcount of the parent with the structureSetParentRefcount method.

A Structure can be created with structureNewEmpty or gst_structure_new(), which both take a name and an optional set of key/value pairs along with the types of the values.

Field values can be changed with structureSetValue or gst_structure_set().

Field values can be retrieved with structureGetValue or the more convenient gst_structure_get_*() functions.

Fields can be removed with structureRemoveField or gst_structure_remove_fields().

Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not allowed. Strings may be Nothing however.

Be aware that the current Caps / Structure serialization into string has limited support for nested Caps / Structure fields. It can only support one level of nesting. Using more levels will lead to unexpected behavior when using serialization features, such as capsToString or valueSerialize and their counterparts.

Exported types

newtype Structure

Memory-managed wrapper type.

Constructors

Structure (ManagedPtr Structure)

Instances

BoxedObject Structure

Defined in GI.Gst.Structs.Structure

Methods

boxedType :: Structure -> IO GType

tag ~ AttrSet => Constructible Structure tag

Defined in GI.Gst.Structs.Structure

Methods

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

newZeroStructure :: MonadIO m => m Structure

Construct a Structure struct initialized to zero.

noStructure :: Maybe Structure

A convenience alias for Nothing :: Maybe Structure.

Methods

canIntersect

structureCanIntersect

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

struct1: a Structure

-> Structure

struct2: a Structure

-> m Bool

Returns: True if intersection would not be empty

Tries intersecting struct1 and struct2 and reports whether the result would not be empty.

copy

structureCopy

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure to duplicate

-> m Structure

Returns: a new Structure.

Duplicates a Structure and all its fields and values.

Free-function: gst_structure_free

filterAndMapInPlace

structureFilterAndMapInPlace

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> StructureFilterMapFunc

func: a function to call for each field

-> m ()

Calls the provided function once for each field in the Structure. In contrast to structureForeach, the function may modify the fields. In contrast to structureMapInPlace, the field is removed from the structure if False is returned from the function. The structure must be mutable.

Since: 1.6

fixate

structureFixate

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> m ()

Fixate all values in structure using valueFixate. structure will be modified in-place and should be writable.

fixateField

structureFixateField

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldName: a field in structure

-> m Bool

Returns: True if the structure field could be fixated

Fixates a Structure by changing the given field with its fixated value.

fixateFieldBoolean

structureFixateFieldBoolean

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldName: a field in structure

-> Bool

target: the target value of the fixation

-> m Bool

Returns: True if the structure could be fixated

Fixates a Structure by changing the given fieldName field to the given target boolean if that field is not fixed yet.

fixateFieldNearestDouble

structureFixateFieldNearestDouble

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldName: a field in structure

-> Double

target: the target value of the fixation

-> m Bool

Returns: True if the structure could be fixated

Fixates a Structure by changing the given field to the nearest double to target that is a subset of the existing field.

fixateFieldNearestFraction

structureFixateFieldNearestFraction

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldName: a field in structure

-> Int32

targetNumerator: The numerator of the target value of the fixation

-> Int32

targetDenominator: The denominator of the target value of the fixation

-> m Bool

Returns: True if the structure could be fixated

Fixates a Structure by changing the given field to the nearest fraction to targetNumerator/targetDenominator that is a subset of the existing field.

fixateFieldNearestInt

structureFixateFieldNearestInt

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldName: a field in structure

-> Int32

target: the target value of the fixation

-> m Bool

Returns: True if the structure could be fixated

Fixates a Structure by changing the given field to the nearest integer to target that is a subset of the existing field.

fixateFieldString

structureFixateFieldString

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldName: a field in structure

-> Text

target: the target value of the fixation

-> m Bool

Returns: True if the structure could be fixated

Fixates a Structure by changing the given fieldName field to the given target string if that field is not fixed yet.

foreach

structureForeach

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> StructureForeachFunc

func: a function to call for each field

-> m Bool

Returns: True if the supplied function returns True For each of the fields, False otherwise.

Calls the provided function once for each field in the Structure. The function must not modify the fields. Also see structureMapInPlace and structureFilterAndMapInPlace.

free

structureFree

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: the Structure to free

-> m ()

Frees a Structure and all its fields and values. The structure must not have a parent when this function is called.

fromString

structureFromString

Arguments

:: (HasCallStack, MonadIO m)

=> Text

string: a string representation of a Structure.

-> m (Maybe Structure, Text)

Returns: a new Structure or Nothing when the string could not be parsed. Free with structureFree after use.

Creates a Structure from a string representation. If end is not Nothing, a pointer to the place inside the given string where parsing ended will be returned.

Free-function: gst_structure_free

getArray

structureGetArray

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, ValueArray)

Returns: True if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a GST_TYPE_ARRAY, this function returns False.

This is useful in language bindings where unknown Value types are not supported. This function will convert the GST_TYPE_ARRAY into a newly allocated ValueArray and return it through array. Be aware that this is slower then getting the Value directly.

getBoolean

structureGetBoolean

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, Bool)

Returns: True if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a boolean, this function returns False.

Sets the boolean pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

getClockTime

structureGetClockTime

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, Word64)

Returns: True if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a GstClockTime, this function returns False.

Sets the clock time pointed to by value corresponding to the clock time of the given field. Caller is responsible for making sure the field exists and has the correct type.

getDate

structureGetDate

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, Date)

Returns: True if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a data, this function returns False.

Sets the date pointed to by value corresponding to the date of the given field. Caller is responsible for making sure the field exists and has the correct type.

On success value will point to a newly-allocated copy of the date which should be freed with dateFree when no longer needed (note: this is inconsistent with e.g. structureGetString which doesn't return a copy of the string).

getDateTime

structureGetDateTime

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, DateTime)

Returns: True if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a data, this function returns False.

Sets the datetime pointed to by value corresponding to the datetime of the given field. Caller is responsible for making sure the field exists and has the correct type.

On success value will point to a reference of the datetime which should be unreffed with dateTimeUnref when no longer needed (note: this is inconsistent with e.g. structureGetString which doesn't return a copy of the string).

getDouble

structureGetDouble

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, Double)

Returns: True if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a double, this function returns False.

Sets the double pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

getEnum

structureGetEnum

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> GType

enumtype: the enum type of a field

-> m (Bool, Int32)

Returns: True if the value could be set correctly. If there was no field with fieldname or the existing field did not contain an enum of the given type, this function returns False.

Sets the int pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists, has the correct type and that the enumtype is correct.

getFieldType

structureGetFieldType

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of the field

-> m GType

Returns: the Value of the field

Finds the field with the given name, and returns the type of the value it contains. If the field is not found, G_TYPE_INVALID is returned.

getFlagset

structureGetFlagset

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, Word32, Word32)

Returns: True if the values could be set correctly. If there was no field with fieldname or the existing field did not contain a GstFlagSet, this function returns False.

Read the GstFlagSet flags and mask out of the structure into the provided pointers.

Since: 1.6

getFraction

structureGetFraction

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, Int32, Int32)

Returns: True if the values could be set correctly. If there was no field with fieldname or the existing field did not contain a GstFraction, this function returns False.

Sets the integers pointed to by valueNumerator and valueDenominator corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

getInt

structureGetInt

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, Int32)

Returns: True if the value could be set correctly. If there was no field with fieldname or the existing field did not contain an int, this function returns False.

Sets the int pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

getInt64

structureGetInt64

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, Int64)

Returns: True if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a gint64, this function returns False.

Sets the gint64 pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

Since: 1.4

getList

structureGetList

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, ValueArray)

Returns: True if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a GST_TYPE_LIST, this function returns False.

Since 1.12

This is useful in language bindings where unknown Value types are not supported. This function will convert the GST_TYPE_LIST into a newly allocated GValueArray and return it through array. Be aware that this is slower then getting the Value directly.

getName

structureGetName

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> m Text

Returns: the name of the structure.

Get the name of structure as a string.

getNameId

structureGetNameId

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> m Word32

Returns: the quark representing the name of the structure.

Get the name of structure as a GQuark.

getString

structureGetString

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Maybe Text)

Returns: a pointer to the string or Nothing when the field did not exist or did not contain a string.

Finds the field corresponding to fieldname, and returns the string contained in the field's value. Caller is responsible for making sure the field exists and has the correct type.

The string should not be modified, and remains valid until the next call to a gst_structure_*() function with the given structure.

getUint

structureGetUint

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, Word32)

Returns: True if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a uint, this function returns False.

Sets the uint pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

getUint64

structureGetUint64

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m (Bool, Word64)

Returns: True if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a guint64, this function returns False.

Sets the guint64 pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

Since: 1.4

getValue

structureGetValue

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of the field to get

-> m (Maybe GValue)

Returns: the Value corresponding to the field with the given name.

Get the value of the field with name fieldname.

hasField

structureHasField

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> m Bool

Returns: True if the structure contains a field with the given name

Check if structure contains a field named fieldname.

hasFieldTyped

structureHasFieldTyped

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> GType

type: the type of a value

-> m Bool

Returns: True if the structure contains a field with the given name and type

Check if structure contains a field named fieldname and with GType type.

hasName

structureHasName

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

name: structure name to check for

-> m Bool

Returns: True if name matches the name of the structure.

Checks if the structure has the given name

idGetValue

structureIdGetValue

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Word32

field: the GQuark of the field to get

-> m (Maybe GValue)

Returns: the Value corresponding to the field with the given name identifier.

Get the value of the field with GQuark field.

idHasField

structureIdHasField

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Word32

field: GQuark of the field name

-> m Bool

Returns: True if the structure contains a field with the given name

Check if structure contains a field named field.

idHasFieldTyped

structureIdHasFieldTyped

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Word32

field: GQuark of the field name

-> GType

type: the type of a value

-> m Bool

Returns: True if the structure contains a field with the given name and type

Check if structure contains a field named field and with GType type.

idSetValue

structureIdSetValue

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Word32

field: a GQuark representing a field

-> GValue

value: the new value of the field

-> m ()

Sets the field with the given GQuark field to value. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed.

idTakeValue

structureIdTakeValue

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Word32

field: a GQuark representing a field

-> GValue

value: the new value of the field

-> m ()

Sets the field with the given GQuark field to value. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed.

intersect

structureIntersect

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

struct1: a Structure

-> Structure

struct2: a Structure

-> m (Maybe Structure)

Returns: Intersection of struct1 and struct2

Intersects struct1 and struct2 and returns the intersection.

isEqual

structureIsEqual

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure1: a Structure.

-> Structure

structure2: a Structure.

-> m Bool

Returns: True if the two structures have the same name and field.

Tests if the two Structure are equal.

isSubset

structureIsSubset

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

subset: a Structure

-> Structure

superset: a potentially greater Structure

-> m Bool

Returns: True if subset is a subset of superset

Checks if subset is a subset of superset, i.e. has the same structure name and for all fields that are existing in superset, subset has a value that is a subset of the value in superset.

mapInPlace

structureMapInPlace

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> StructureMapFunc

func: a function to call for each field

-> m Bool

Returns: True if the supplied function returns True For each of the fields, False otherwise.

Calls the provided function once for each field in the Structure. In contrast to structureForeach, the function may modify but not delete the fields. The structure must be mutable.

nFields

structureNFields

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> m Int32

Returns: the number of fields in the structure

Get the number of fields in the structure.

newEmpty

structureNewEmpty

Arguments

:: (HasCallStack, MonadIO m)

=> Text

name: name of new structure

-> m Structure

Returns: a new, empty Structure

Creates a new, empty Structure with the given name.

See structureSetName for constraints on the name parameter.

Free-function: gst_structure_free

newFromString

structureNewFromString

Arguments

:: (HasCallStack, MonadIO m)

=> Text

string: a string representation of a Structure

-> m (Maybe Structure)

Returns: a new Structure or Nothing when the string could not be parsed. Free with structureFree after use.

Creates a Structure from a string representation. If end is not Nothing, a pointer to the place inside the given string where parsing ended will be returned.

The current implementation of serialization will lead to unexpected results when there are nested Caps / Structure deeper than one level.

Free-function: gst_structure_free

Since: 1.2

newIdEmpty

structureNewIdEmpty

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

quark: name of new structure

-> m Structure

Returns: a new, empty Structure

Creates a new, empty Structure with the given name as a GQuark.

Free-function: gst_structure_free

nthFieldName

structureNthFieldName

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Word32

index: the index to get the name of

-> m Text

Returns: the name of the given field number

Get the name of the given field number, counting from 0 onwards.

removeAllFields

structureRemoveAllFields

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> m ()

Removes all fields in a GstStructure.

removeField

structureRemoveField

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of the field to remove

-> m ()

Removes the field with the given name. If the field with the given name does not exist, the structure is unchanged.

setArray

structureSetArray

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> ValueArray

array: a pointer to a ValueArray

-> m ()

This is useful in language bindings where unknown GValue types are not supported. This function will convert a array to GST_TYPE_ARRAY and set the field specified by fieldname. Be aware that this is slower then using GST_TYPE_ARRAY in a Value directly.

Since 1.12

setList

structureSetList

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of a field

-> ValueArray

array: a pointer to a ValueArray

-> m ()

This is useful in language bindings where unknown GValue types are not supported. This function will convert a array to GST_TYPE_LIST and set the field specified by fieldname. Be aware that this is slower then using GST_TYPE_LIST in a Value directly.

Since 1.12

setName

structureSetName

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

name: the new name of the structure

-> m ()

Sets the name of the structure to the given name. The string provided is copied before being used. It must not be empty, start with a letter and can be followed by letters, numbers and any of "/-_.:".

setParentRefcount

structureSetParentRefcount

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Int32

refcount: a pointer to the parent's refcount

-> m Bool

Returns: True if the parent refcount could be set.

Sets the parent_refcount field of Structure. This field is used to determine whether a structure is mutable or not. This function should only be called by code implementing parent objects of Structure, as described in the MT Refcounting section of the design documents.

setValue

structureSetValue

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of the field to set

-> GValue

value: the new value of the field

-> m ()

Sets the field with the given name field to value. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed.

takeValue

structureTakeValue

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> Text

fieldname: the name of the field to set

-> GValue

value: the new value of the field

-> m ()

Sets the field with the given name field to value. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. The function will take ownership of value.

toString

structureToString

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

structure: a Structure

-> m Text

Returns: a pointer to string allocated by malloc. free after usage.

Converts structure to a human-readable string representation.

For debugging purposes its easier to do something like this:

C code

GST_LOG ("structure is %" GST_PTR_FORMAT, structure);

This prints the structure in human readable form.

The current implementation of serialization will lead to unexpected results when there are nested Caps / Structure deeper than one level.

Free-function: g_free

Properties

type

the GType of a structure

getStructureType :: MonadIO m => Structure -> m GType

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

get structure #type

setStructureType :: MonadIO m => Structure -> GType -> m ()

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

set structure [ #type := value ]