gi-gst-1.0.22: GStreamer bindings
Copyright Will Thompson Iñaki García Etxebarria and Jonas Platte LGPL-2.1 Iñaki García Etxebarria None Haskell2010

GI.Gst.Structs.Structure

Description

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.

Synopsis

# Exported types

newtype Structure Source #

Memory-managed wrapper type.

Constructors

 Structure (ManagedPtr Structure)

#### Instances

Instances details
 Source # Instance detailsDefined in GI.Gst.Structs.Structure Methods Source # Instance detailsDefined in GI.Gst.Structs.Structure Methods Source # Convert Structure to and from GValue with toGValue and fromGValue. Instance detailsDefined in GI.Gst.Structs.Structure Methods tag ~ 'AttrSet => Constructible Structure tag Source # Instance detailsDefined in GI.Gst.Structs.Structure Methodsnew :: MonadIO m => (ManagedPtr Structure -> Structure) -> [AttrOp Structure tag] -> m Structure #

Construct a Structure struct initialized to zero.

A convenience alias for Nothing :: Maybe Structure.

# Methods

## canIntersect

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Arguments

 :: (HasCallStack, MonadIO m) => Structure structure: a Structure -> m ()

Removes all fields in a GstStructure.

## removeField

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

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

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

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

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

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

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

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

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

get structure #type


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

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

set structure [ #type := value ]