Structure

A gstreamer.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 gstreamer.Structure also has a name. The name starts with a letter and can be filled by letters, numbers and any of "/-_.:".

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

A gstreamer.Structure can be created with Structure.newEmpty or 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 Structure.setValue or Structure.set.

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

Fields can be removed with Structure.removeField or Structure.removeFields.

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

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

class Structure {
bool ownedRef;
}

Constructors

this
this(GstStructure* gstStructure, bool ownedRef = false)

Sets our main struct and passes it to the parent class.

this
this(string name)

Creates a new, empty gstreamer.Structure with the given name.

this
this(GQuark quark)

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

this
this(string name, string firstfield, void* varargs)

Creates a new gstreamer.Structure with the given name. Structure fields are set according to the varargs in a manner similar to Structure.new.

Destructor

A destructor is present on this object, but not explicitly documented in the source.

Members

Functions

canIntersect
bool canIntersect(Structure struct2)

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

copy
Structure copy()

Duplicates a gstreamer.Structure and all its fields and values.

filterAndMapInPlace
void filterAndMapInPlace(GstStructureFilterMapFunc func, void* userData)

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

fixate
void fixate()

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

fixateField
bool fixateField(string fieldName)

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

fixateFieldBoolean
bool fixateFieldBoolean(string fieldName, bool target)

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

fixateFieldNearestDouble
bool fixateFieldNearestDouble(string fieldName, double target)

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

fixateFieldNearestFraction
bool fixateFieldNearestFraction(string fieldName, int targetNumerator, int targetDenominator)

Fixates a gstreamer.Structure by changing the given field to the nearest fraction to target_numerator/target_denominator that is a subset of the existing field.

fixateFieldNearestInt
bool fixateFieldNearestInt(string fieldName, int target)

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

fixateFieldString
bool fixateFieldString(string fieldName, string target)

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

foreac
bool foreac(GstStructureForeachFunc func, void* userData)

Calls the provided function once for each field in the gstreamer.Structure The function must not modify the fields. Also see Structure.mapInPlace and Structure.filterAndMapInPlace.

free
void free()

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

getArray
bool getArray(string fieldname, out ValueArray array)

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

getBoolean
bool getBoolean(string fieldname, out bool value)

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
bool getClockTime(string fieldname, out GstClockTime value)

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
bool getDate(string fieldname, out Date value)

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.

getDateTime
bool getDateTime(string fieldname, out DateTime value)

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.

getDouble
bool getDouble(string fieldname, out double value)

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
bool getEnum(string fieldname, GType enumtype, out int value)

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
GType getFieldType(string fieldname)

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
bool getFlagset(string fieldname, out uint valueFlags, out uint valueMask)

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

getFraction
bool getFraction(string fieldname, out int valueNumerator, out int valueDenominator)

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

getInt
bool getInt(string fieldname, out int value)

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
bool getInt64(string fieldname, out long value)

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.

getList
bool getList(string fieldname, out ValueArray array)

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

getName
string getName()

Get the name of structure as a string.

getNameId
GQuark getNameId()

Get the name of structure as a GQuark.

getString
string getString(string fieldname)

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.

getStruct
void* getStruct()

the main Gtk struct as a void*

getStructureStruct
GstStructure* getStructureStruct(bool transferOwnership = false)

Get the main Gtk struct

getUint
bool getUint(string fieldname, out uint value)

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
bool getUint64(string fieldname, out ulong value)

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.

getValist
bool getValist(string firstFieldname, void* args)

Parses the variable arguments and reads fields from structure accordingly. valist-variant of Structure.get. Look at the documentation of Structure.get for more details.

getValue
Value getValue(string fieldname)

Get the value of the field with name fieldname.

hasField
bool hasField(string fieldname)

Check if structure contains a field named fieldname.

hasFieldTyped
bool hasFieldTyped(string fieldname, GType type)

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

hasName
bool hasName(string name)

Checks if the structure has the given name

idGetValist
bool idGetValist(GQuark firstFieldId, void* args)

Parses the variable arguments and reads fields from structure accordingly. valist-variant of Structure.idGet. Look at the documentation of Structure.idGet for more details.

idGetValue
Value idGetValue(GQuark field)

Get the value of the field with GQuark field.

idHasField
bool idHasField(GQuark field)

Check if structure contains a field named field.

idHasFieldTyped
bool idHasFieldTyped(GQuark field, GType type)

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

idSetValist
void idSetValist(GQuark fieldname, void* varargs)

va_list form of Structure.idSet.

idSetValue
void idSetValue(GQuark field, Value value)

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
void idTakeValue(GQuark field, Value value)

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
Structure intersect(Structure struct2)

Intersects struct1 and struct2 and returns the intersection.

isEqual
bool isEqual(Structure structure2)

Tests if the two gstreamer.Structure are equal.

isSubset
bool isSubset(Structure 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
bool mapInPlace(GstStructureMapFunc func, void* userData)

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

nFields
int nFields()

Get the number of fields in the structure.

nthFieldName
string nthFieldName(uint index)

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

removeAllFields
void removeAllFields()

Removes all fields in a GstStructure.

removeField
void removeField(string fieldname)

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

removeFieldsValist
void removeFieldsValist(string fieldname, void* varargs)

va_list form of Structure.removeFields.

setArray
void setArray(string fieldname, ValueArray array)

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 gobject.Value directly.

setList
void setList(string fieldname, ValueArray array)

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 gobject.Value directly.

setName
void setName(string name)

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
bool setParentRefcount(int* refcount)

Sets the parent_refcount field of gstreamer.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 gstreamer.Structure, as described in the MT Refcounting section of the design documents.

setValist
void setValist(string fieldname, void* varargs)

va_list form of Structure.set.

setValue
void setValue(string fieldname, Value value)

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
void takeValue(string fieldname, Value value)

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
string toString()

Converts structure to a human-readable string representation.

Static functions

fromString
Structure fromString(string str, out string end)

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

getType
GType getType()

Variables

gstStructure
GstStructure* gstStructure;

the main Gtk struct

Meta