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
set_parent_refcount method.
A Structure can be created with
Structure.empty or Structure, 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 set_value or
@set.
Field values can be retrieved with get_value or the more convenient
gst_structure_get_*() functions.
Fields can be removed with remove_field or
remove_fields.
Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not allowed. Strings may be null however.
typeof (unichar2)
typeof (unichar2) 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 to_string, all values are
explicitly typed.
Some types have special delimiters:
- [GstValueArray](GST_TYPE_ARRAY) 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](GST_TYPE_LIST) 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 semicolon `;` the latter allowing to store multiple structures in the same string
(see Caps).
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" ```
Since 1.20, nested structures and caps can be specified using brackets (`[` and `]`), for example:
``` a-struct, nested=[nested-struct, nested=true] ```
> *note*: to_string won't use that syntax for backward >
compatibility reason, serialize has been added for > that purpose.
- public bool @foreach (StructureForeachFunc func)
Calls the provided function once for each field in the
Structure.
- public bool @get (...)
Parses the variable arguments and reads fields from
this accordingly.
- public void @set (string fieldname, ...)
Parses the variable arguments and sets fields accordingly.
- public bool can_intersect (Structure struct2)
Tries intersecting this and struct2
and reports whether the result would not be empty.
- public Structure copy ()
Duplicates a Structure and all its fields and
values.
- public void filter_and_map_in_place (StructureFilterMapFunc func)
Calls the provided function once for each field in the
Structure.
- public void fixate ()
Fixate all values in this using
fixate.
- public bool fixate_field (string field_name)
Fixates a Structure by changing the given field
with its fixated value.
- public bool fixate_field_boolean (string field_name, bool target)
Fixates a Structure by changing the given
field_name field to the given target boolean if that field is not fixed yet.
- public bool fixate_field_nearest_double (string field_name, double target)
Fixates a Structure by changing the given field
to the nearest double to target that is a subset of the existing field.
- public bool fixate_field_nearest_fraction (string field_name, int target_numerator, int target_denominator)
Fixates a Structure by changing the given field
to the nearest fraction to target_numerator/target_denominator that is a subset of the existing field.
- public bool fixate_field_nearest_int (string field_name, int target)
Fixates a Structure by changing the given field
to the nearest integer to target that is a subset of the existing field.
- public bool fixate_field_string (string field_name, string target)
Fixates a Structure by changing the given
field_name field to the given target string if that field is not fixed yet.
- public void free ()
Frees a Structure and all its fields and values.
- public bool get_array (string fieldname, out ValueArray array)
This is useful in language bindings where unknown
Value types are not supported.
- public bool get_boolean (string fieldname, out bool value)
Sets the boolean pointed to by value corresponding to the value
of the given field.
- public bool get_clock_time (string fieldname, out ClockTime value)
Sets the clock time pointed to by value corresponding to the
clock time of the given field.
- public bool get_date (string fieldname, out Date value)
Sets the date pointed to by value corresponding to the date of
the given field.
- public bool get_date_time (string fieldname, out DateTime value)
Sets the datetime pointed to by value corresponding to the
datetime of the given field.
- public bool get_double (string fieldname, out double value)
Sets the double pointed to by value corresponding to the value
of the given field.
- public bool get_enum (string fieldname, Type enumtype, out int value)
Sets the int pointed to by value corresponding to the value of
the given field.
- public Type get_field_type (string fieldname)
Finds the field with the given name, and returns the type of the value it
contains.
- public bool get_flags (string fieldname, Type flags_type, out uint value)
Sets the unsigned int pointed to by value corresponding to the
value of the given field.
- public bool get_flagset (string fieldname, out uint value_flags, out uint value_mask)
Read the GstFlagSet flags and mask out of the structure into the provided
pointers.
- public bool get_fraction (string fieldname, out int value_numerator, out int value_denominator)
Sets the integers pointed to by value_numerator and
value_denominator corresponding to the value of the given field.
- public bool get_int (string fieldname, out int value)
Sets the int pointed to by value corresponding to the value of
the given field.
- public bool get_int64 (string fieldname, out int64 value)
Sets the int64 pointed to
by value corresponding to the value of the given field.
- public bool get_list (string fieldname, out ValueArray array)
This is useful in language bindings where unknown
Value types are not supported.
- public unowned string get_name ()
Get the name of this as a string.
- public Quark get_name_id ()
Get the name of this as a GQuark.
- public unowned string? get_string (string fieldname)
Finds the field corresponding to fieldname, and returns the
string contained in the field's value.
- public bool get_uint (string fieldname, out uint value)
Sets the uint pointed to by value corresponding to the value of
the given field.
- public bool get_uint64 (string fieldname, out uint64 value)
Sets the uint64 pointed
to by value corresponding to the value of the given field.
- public bool get_valist (string first_fieldname, va_list args)
Parses the variable arguments and reads fields from
this accordingly.
- public unowned Value? get_value (string fieldname)
Get the value of the field with name fieldname.
- public bool has_field (string fieldname)
Check if this contains a field named
fieldname.
- public bool has_field_typed (string fieldname, Type type)
Check if this contains a field named
fieldname and with GType type.
- public bool has_name (string name)
Checks if the structure has the given name
- public bool id_get (...)
Parses the variable arguments and reads fields from
this accordingly.
- public bool id_get_valist (Quark first_field_id, va_list args)
Parses the variable arguments and reads fields from
this accordingly.
- public unowned Value? id_get_value (Quark field)
Get the value of the field with GQuark field.
- public bool id_has_field (Quark field)
Check if this contains a field named
field.
- public bool id_has_field_typed (Quark field, Type type)
Check if this contains a field named
field and with GType type.
- public void id_set (Quark fieldname, ...)
Identical to gst_structure_set, except that field names are passed using the
GQuark for the field name.
- public void id_set_valist (Quark fieldname, va_list varargs)
- public void id_set_value (Quark field, Value value)
Sets the field with the given GQuark field to value
.
- public void id_take_value (Quark field, owned Value value)
Sets the field with the given GQuark field to value
.
- public Structure? intersect (Structure struct2)
Intersects this and struct2
and returns the intersection.
- public bool is_equal (Structure structure2)
Tests if the two Structure are equal.
- public bool is_subset (Structure superset)
Checks if this is a subset of
superset, i.e. has the same structure name and for all fields that are existing in superset,
this has a value that is a subset of the value in superset.
- public bool map_in_place (StructureMapFunc func)
Calls the provided function once for each field in the
Structure.
- public int n_fields ()
Get the number of fields in the structure.
- public unowned string nth_field_name (uint index)
Get the name of the given field number, counting from 0 onwards.
- public void remove_all_fields ()
Removes all fields in a GstStructure.
- public void remove_field (string fieldname)
Removes the field with the given name.
- public void remove_fields (string[] field_names)
Removes the fields with the given names.
- public void remove_fields_valist (string fieldname, va_list varargs)
- public string serialize (SerializeFlags flags)
Converts this to a human-readable string
representation.
- public void set_array (string fieldname, ValueArray array)
This is useful in language bindings where unknown GValue types are not
supported.
- public void set_list (string fieldname, ValueArray array)
This is useful in language bindings where unknown GValue types are not
supported.
- public void set_name (string name)
Sets the name of the structure to the given name.
- public bool set_parent_refcount (int refcount)
Sets the parent_refcount field of Structure.
- public void set_valist (string fieldname, va_list varargs)
- public void set_value (string fieldname, Value value)
Sets the field with the given name field to value.
- public void take_value (string fieldname, owned Value value)
Sets the field with the given name field to value.
- public string to_string ()
Converts this to a human-readable string
representation.