Structure

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

#GstStructure is used by various GStreamer subsystems to store information in a flexible and extensible way. A #GstStructure does not have a refcount because it usually is part of a higher level object such as #GstCaps, #GstMessage, #GstEvent, #GstQuery. It provides a means to enforce mutability using the refcount of the parent with the gst_structure_set_parent_refcount() method.

A #GstStructure can be created with gst_structure_new_empty() 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 gst_structure_set_value() or gst_structure_set().

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

Fields can be removed with gst_structure_remove_field() or gst_structure_remove_fields().

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

The serialization format

GstStructure serialization format serialize the GstStructure name, keys/GType/values in a comma separated list with the structure name as first field without value followed by separated key/value pairs in the form key=value, for example:

a-structure, key=value
`

The values type will be inferred if not explicitly specified with the (GTypeName)value syntax, for example the following struct will have one field called 'is-string' which has the string 'true' as a value:

a-struct, field-is-string=(string)true, field-is-boolean=true

*Note*: without specifying (string), field-is-string` type would have been inferred as boolean.

*Note*: we specified (string) as a type even if gchararray is the actual GType name as for convenience some well known types have been aliased or abbreviated.

To avoid specifying the type, you can give some hints to the "type system". For example to specify a value as a double, you should add a decimal (ie. 1 is an int while 1.0 is a double).

*Note*: when a structure is serialized with #gst_structure_to_string, all values are explicitly typed.

Some types have special delimiters:

- GstValueArray are inside curly brackets ({ and }). For example a-structure, array={1, 2, 3} - Ranges are inside brackets ([ and ]). For example `a-structure, range=[1, 6, 2]` 1 being the min value, 6 the maximum and 2 the step. To specify a #GST_TYPE_INT64_RANGE you need to explicitly specify it like: a-structure, a-int64-range=(gint64) [1, 5] - GstValueList are inside "less and greater than" (< and >). For example `a-structure, list=<1, 2, 3>

Structures are delimited either by a null character \0 or a semicolumn ; the latter allowing to store multiple structures in the same string (see #GstCaps).

Quotes are used as "default" delimiters and can be used around any types that don't use other delimiters (for example a-struct, i=(int)"1"). They are use to allow adding spaces or special characters (such as delimiters, semicolumns, etc..) inside strings and you can use backslashes \ to escape characters inside them, for example:

a-struct, special="\"{[(;)]}\" can be used inside quotes"

They also allow for nested structure, such as:

a-struct, nested=(GstStructure)"nested-struct, nested=true"

> *Note*: Be aware that the current #GstCaps / #GstStructure serialization > into string has limited support for nested #GstCaps / #GstStructure fields. > It can only support one level of nesting. Using more levels will lead to > unexpected behavior when using serialization features, such as > gst_caps_to_string() or gst_value_serialize() and their counterparts.

class Structure {

protected

GstStructure* gstStructure;

protected

bool ownedRef;

GstStructure* getStructureStruct(bool transferOwnership);

void* getStruct();

this(GstStructure* gstStructure, bool ownedRef);

~this();

static Structure fromString(string name);

static GType getType();

this(string string_, string end);

this(string name);

this(GQuark quark);

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

bool canIntersect(Structure struct2);

Structure copy();

void filterAndMapInPlace(GstStructureFilterMapFunc func, void* userData);

void fixate();

bool fixateField(string fieldName);

bool fixateFieldBoolean(string fieldName, bool target);

bool fixateFieldNearestDouble(string fieldName, double target);

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

bool fixateFieldNearestInt(string fieldName, int target);

bool fixateFieldString(string fieldName, string target);

alias foreac = foreach_;

bool foreach_(GstStructureForeachFunc func, void* userData);

void free();

bool getArray(string fieldname, ValueArray array);

bool getBoolean(string fieldname, bool value);

bool getClockTime(string fieldname, GstClockTime value);

bool getDate(string fieldname, Date value);

bool getDateTime(string fieldname, DateTime value);

bool getDouble(string fieldname, double value);

bool getEnum(string fieldname, GType enumtype, int value);

GType getFieldType(string fieldname);

bool getFlagset(string fieldname, uint valueFlags, uint valueMask);

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

bool getInt(string fieldname, int value);

bool getInt64(string fieldname, long value);

bool getList(string fieldname, ValueArray array);

string getName();

GQuark getNameId();

string getString(string fieldname);

bool getUint(string fieldname, uint value);

bool getUint64(string fieldname, ulong value);

bool getValist(string firstFieldname, void* args);

Value getValue(string fieldname);

bool hasField(string fieldname);

bool hasFieldTyped(string fieldname, GType type);

bool hasName(string name);

bool idGetValist(GQuark firstFieldId, void* args);

Value idGetValue(GQuark field);

bool idHasField(GQuark field);

bool idHasFieldTyped(GQuark field, GType type);

void idSetValist(GQuark fieldname, void* varargs);

void idSetValue(GQuark field, Value value);

void idTakeValue(GQuark field, Value value);

Structure intersect(Structure struct2);

bool isEqual(Structure structure2);

bool isSubset(Structure superset);

bool mapInPlace(GstStructureMapFunc func, void* userData);

int nFields();

string nthFieldName(uint index);

void removeAllFields();

void removeField(string fieldname);

void removeFieldsValist(string fieldname, void* varargs);

void setArray(string fieldname, ValueArray array);

void setList(string fieldname, ValueArray array);

void setName(string name);

bool setParentRefcount(int* refcount);

void setValist(string fieldname, void* varargs);

void setValue(string fieldname, Value value);

void takeValue(string fieldname, Value value);

string toString();

static bool take(Structure oldstrPtr, Structure newstr);

}

Constructors

this this(GstStructure* gstStructure, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(string string_, string end): Creates a #GstStructure from a string representation. If end is not %NULL, a pointer to the place inside the given string where parsing ended will be returned.
this this(string name): Creates a new, empty #GstStructure with the given @name.
this this(GQuark quark): Creates a new, empty #GstStructure with the given name as a GQuark.
this this(string name, string firstfield, void* varargs): Creates a new #GstStructure with the given @name. Structure fields are set according to the varargs in a manner similar to gst_structure_new().

Destructor

~this ~this(): Undocumented in source.

Members

Aliases

foreac alias foreac = foreach_: Undocumented in source.

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 #GstStructure and all its fields and values.
filterAndMapInPlace void filterAndMapInPlace(GstStructureFilterMapFunc func, void* userData): Calls the provided function once for each field in the #GstStructure. In contrast to gst_structure_foreach(), the function may modify the fields. In contrast to gst_structure_map_in_place(), 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 gst_value_fixate(). @structure will be modified in-place and should be writable.
fixateField bool fixateField(string fieldName): Fixates a #GstStructure by changing the given field with its fixated value.
fixateFieldBoolean bool fixateFieldBoolean(string fieldName, bool target): Fixates a #GstStructure 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 #GstStructure 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 #GstStructure 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 #GstStructure 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 #GstStructure by changing the given @field_name field to the given @target string if that field is not fixed yet.
foreach_ bool foreach_(GstStructureForeachFunc func, void* userData): Calls the provided function once for each field in the #GstStructure. The function must not modify the fields. Also see gst_structure_map_in_place() and gst_structure_filter_and_map_in_place().
free void free(): Frees a #GstStructure and all its fields and values. The structure must not have a parent when this function is called.
getArray bool getArray(string fieldname, ValueArray array): This is useful in language bindings where unknown #GValue types are not supported. This function will convert the %GST_TYPE_ARRAY into a newly allocated #GValueArray and return it through @array. Be aware that this is slower then getting the #GValue directly.
getBoolean bool getBoolean(string fieldname, 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, 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, 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, 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, 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, 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, uint valueFlags, uint valueMask): Read the GstFlagSet flags and mask out of the structure into the provided pointers.
getFraction bool getFraction(string fieldname, int valueNumerator, 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, 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, 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, ValueArray array): This is useful in language bindings where unknown #GValue 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 #GValue 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): Get the main Gtk struct
getUint bool getUint(string fieldname, 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, 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 gst_structure_get(). Look at the documentation of gst_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 gst_structure_id_get(). Look at the documentation of gst_structure_id_get() 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 gst_structure_id_set().
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 #GstStructure 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 #GstStructure. In contrast to gst_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 gst_structure_remove_fields().
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 #GValue 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_LIST and set the field specified by @fieldname. Be aware that this is slower then using %GST_TYPE_LIST in a #GValue 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 #GstStructure. 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 #GstStructure, as described in the MT Refcounting section of the design documents.
setValist void setValist(string fieldname, void* varargs): va_list form of gst_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 name): Undocumented in source. Be warned that the author may not have intended to support it.
getType GType getType()
take bool take(Structure oldstrPtr, Structure newstr): Atomically modifies a pointer to point to a new structure. The #GstStructure @oldstr_ptr is pointing to is freed and @newstr is taken ownership over.

Variables

gstStructure GstStructure* gstStructure;: the main Gtk struct
ownedRef bool ownedRef;: Undocumented in source.