gst.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.Structure.setParentRefcount method.

A #GstStructure can be created with gst.structure.Structure.newEmpty or gst.structure.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.Structure.setValue or gst.structure.Structure.set.

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

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

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 [harfbuzz.types.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](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 #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"

Since 1.20, nested structures and caps can be specified using brackets (`[` and `]`), for example:

a-struct, nested=[nested-struct, nested=true]

note: gst.structure.Structure.toString_ won't use that syntax for backward

compatibility reason, gst.structure.Structure.serializeFull has been added for that purpose.