Gst.Structure – gstreamer-1.0 Reference Manual

Structure

Object Hierarchy:

Gst.Structure Gst.Structure Gst.Structure

Description:

[ CCode ( copy_function = "gst_structure_copy" , free_function = "gst_structure_free" , type_id = "gst_structure_get_type ()" ) ]
[ Compact ]
public class Structure

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.


Namespace: Gst
Package: gstreamer-1.0

Content:

Static methods:

Creation methods:

Methods:

Fields:



2022 vala-language.org