Structure#

class Structure(*args, **kwargs)#

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 new_empty() or 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 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 None 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 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*\: :func:`~gi.repository.Gst.Structure.to_string` won't use that syntax for backward
compatibility reason, :func:`~gi.repository.Gst.Structure.serialize_full` has been added for
that purpose.

Constructors#

class Structure

classmethod from_string(string: str) → Tuple[Structure | None, str]#

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

Free-function: gst_structure_free

Parameters:: string – a string representation of a Structure.

classmethod new_empty(name: str) → Structure#

Creates a new, empty Structure with the given name.

See set_name() for constraints on the name parameter.

Free-function: gst_structure_free

Parameters:: name – name of new structure

classmethod new_from_string(string: str) → Structure | None#

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

The current implementation of serialization will lead to unexpected results when there are nested Caps / Structure deeper than one level unless the serialize() function is used (without GST_SERIALIZE_FLAG_BACKWARD_COMPAT)

Free-function: gst_structure_free

Added in version 1.2.

Parameters:: string – a string representation of a Structure

classmethod new_id_empty(quark: int) → Structure#

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

Free-function: gst_structure_free

Parameters:: quark – name of new structure

Methods#

class Structure

can_intersect(struct2: Structure) → bool#

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

Parameters:: struct2 – a Structure

filter_and_map_in_place(func: Callable[[int, Value, Any], bool], user_data: Any = None) → None#

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

Added in version 1.6.

Parameters:

func – a function to call for each field
user_data – private data

fixate() → None#: Fixate all values in structure using value_fixate(). structure will be modified in-place and should be writable.

fixate_field(field_name: str) → bool#

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

Parameters:: field_name – a field in structure

fixate_field_boolean(field_name: str, target: bool) → bool#

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

Parameters:

field_name – a field in structure
target – the target value of the fixation

fixate_field_nearest_double(field_name: str, target: float) → bool#

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

Parameters:

field_name – a field in structure
target – the target value of the fixation

fixate_field_nearest_fraction(field_name: str, target_numerator: int, target_denominator: int) → bool#

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.

Parameters:

field_name – a field in structure
target_numerator – The numerator of the target value of the fixation
target_denominator – The denominator of the target value of the fixation

fixate_field_nearest_int(field_name: str, target: int) → bool#

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

Parameters:

field_name – a field in structure
target – the target value of the fixation

fixate_field_string(field_name: str, target: str) → bool#

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

Parameters:

field_name – a field in structure
target – the target value of the fixation

foreach(func: Callable[[int, Value, Any], bool], user_data: Any = None) → bool#

Calls the provided function once for each field in the Structure. The function must not modify the fields. Also see map_in_place() and filter_and_map_in_place().

Parameters:

func – a function to call for each field
user_data – private data

free() → None#: Frees a Structure and all its fields and values. The structure must not have a parent when this function is called.

get_array(fieldname: str) → Tuple[bool, ValueArray]#

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

Added in version 1.12.

Parameters:: fieldname – the name of a field

get_boolean(fieldname: str) → Tuple[bool, bool]#

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.

Parameters:: fieldname – the name of a field

get_clock_time(fieldname: str) → Tuple[bool, int]#

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.

Parameters:: fieldname – the name of a field

get_date(fieldname: str) → Tuple[bool, Date]#

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.

On success value will point to a newly-allocated copy of the date which should be freed with free() when no longer needed (note: this is inconsistent with e.g. get_string() which doesn’t return a copy of the string).

Parameters:: fieldname – the name of a field

get_date_time(fieldname: str) → Tuple[bool, DateTime]#

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.

On success value will point to a reference of the datetime which should be unreffed with unref() when no longer needed (note: this is inconsistent with e.g. get_string() which doesn’t return a copy of the string).

Parameters:: fieldname – the name of a field

get_double(fieldname: str) → Tuple[bool, float]#

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.

Parameters:: fieldname – the name of a field

get_enum(fieldname: str, enumtype: GType) → Tuple[bool, int]#

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.

Parameters:

fieldname – the name of a field
enumtype – the enum type of a field

get_field_type(fieldname: str) → GType#

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.

Parameters:: fieldname – the name of the field

get_flags(fieldname: str, flags_type: GType) → Tuple[bool, int]#

Sets the unsigned 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 flagstype is correct.

Added in version 1.22.

Parameters:

fieldname – the name of a field
flags_type – the flags type of a field

get_flagset(fieldname: str) → Tuple[bool, int, int]#

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

Added in version 1.6.

Parameters:: fieldname – the name of a field

get_fraction(fieldname: str) → Tuple[bool, int, int]#

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.

Parameters:: fieldname – the name of a field

get_int(fieldname: str) → Tuple[bool, int]#

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.

Parameters:: fieldname – the name of a field

get_int64(fieldname: str) → Tuple[bool, int]#

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.

Added in version 1.4.

Parameters:: fieldname – the name of a field

get_list(fieldname: str) → Tuple[bool, ValueArray]#

This is useful in language bindings where unknown Value 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 Value directly.

Added in version 1.12.

Parameters:: fieldname – the name of a field

get_name() → str#: Get the name of structure as a string.

get_name_id() → int#: Get the name of structure as a GQuark.

get_string(fieldname: str) → str | None#

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.

The string should not be modified, and remains valid until the next call to a gst_structure_*() function with the given structure.

Parameters:: fieldname – the name of a field

get_uint(fieldname: str) → Tuple[bool, int]#

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.

Parameters:: fieldname – the name of a field

get_uint64(fieldname: str) → Tuple[bool, int]#

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.

Added in version 1.4.

Parameters:: fieldname – the name of a field

get_value(fieldname: str) → Value | None#

Get the value of the field with name fieldname.

Parameters:: fieldname – the name of the field to get

has_field(fieldname: str) → bool#

Check if structure contains a field named fieldname.

Parameters:: fieldname – the name of a field

has_field_typed(fieldname: str, type: GType) → bool#

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

Parameters:

fieldname – the name of a field
type – the type of a value

has_name(name: str) → bool#

Checks if the structure has the given name

Parameters:: name – structure name to check for

id_get_value(field: int) → Value | None#

Get the value of the field with GQuark field.

Parameters:: field – the Quark of the field to get

id_has_field(field: int) → bool#

Check if structure contains a field named field.

Parameters:: field – Quark of the field name

id_has_field_typed(field: int, type: GType) → bool#

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

Parameters:

field – Quark of the field name
type – the type of a value

id_set_value(field: int, value: Value) → None#

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.

Parameters:

field – a Quark representing a field
value – the new value of the field

id_take_value(field: int, value: Value) → None#

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.

Parameters:

field – a Quark representing a field
value – the new value of the field

intersect(struct2: Structure) → Structure | None#

Intersects struct1 and struct2 and returns the intersection.

Parameters:: struct2 – a Structure

is_equal(structure2: Structure) → bool#

Tests if the two Structure are equal.

Parameters:: structure2 – a Structure.

is_subset(superset: Structure) → bool#

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.

Parameters:: superset – a potentially greater Structure

map_in_place(func: Callable[[int, Value, Any], bool], user_data: Any = None) → bool#

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

Parameters:

func – a function to call for each field
user_data – private data

n_fields() → int#: Get the number of fields in the structure.

nth_field_name(index: int) → str#

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

Parameters:: index – the index to get the name of

remove_all_fields() → None#: Removes all fields in a GstStructure.

remove_field(fieldname: str) → None#

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

Parameters:: fieldname – the name of the field to remove

serialize(flags: SerializeFlags) → str#

Converts structure to a human-readable string representation.

This version of the caps serialization function introduces support for nested structures and caps but the resulting strings won’t be parsable with GStreamer prior to 1.20 unless GST_SERIALIZE_FLAG_BACKWARD_COMPAT is passed as flag.

STRICT flags is not allowed because it would make this function nullable which is an API break for bindings. Use serialize_full() instead.

Free-function: g_free

Added in version 1.20.

Deprecated since version Unknown: Use serialize_full() instead.

Parameters:: flags – The flags to use to serialize structure

serialize_full(flags: SerializeFlags) → str | None#

Alias for serialize() but with nullable annotation because it can return None when STRICT flag is set.

Added in version 1.24.

Parameters:: flags – The flags to use to serialize structure

set_array(fieldname: str, array: ValueArray) → None#

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

Added in version 1.12.

Parameters:

fieldname – the name of a field
array – a pointer to a ValueArray

set_list(fieldname: str, array: ValueArray) → None#

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

Added in version 1.12.

Parameters:

fieldname – the name of a field
array – a pointer to a ValueArray

set_name(name: str) → None#

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 “/-_.:”.

Parameters:: name – the new name of the structure

set_parent_refcount(refcount: int) → bool#

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

Parameters:: refcount – a pointer to the parent’s refcount

set_value(fieldname: str, value: Value) → None#

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.

Parameters:

fieldname – the name of the field to set
value – the new value of the field

classmethod take(newstr: Structure | None = None) → Tuple[bool, Structure | None]#

Atomically modifies a pointer to point to a new structure. The Structure oldstr_ptr is pointing to is freed and newstr is taken ownership over.

Either newstr and the value pointed to by oldstr_ptr may be None.

It is a programming error if both newstr and the value pointed to by oldstr_ptr refer to the same, non-None structure.

Added in version 1.18.

Parameters:: newstr – a new Structure

take_value(fieldname: str, value: Value) → None#

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.

Parameters:

fieldname – the name of the field to set
value – the new value of the field

to_string() → str#

Converts structure to a human-readable string representation.

For debugging purposes its easier to do something like this: |[<!– language=”C” –> GST_LOG (“structure is %” GST_PTR_FORMAT, structure);

This prints the structure in human readable form.

This function will lead to unexpected results when there are nested Caps / Structure deeper than one level, you should user serialize_full() instead for those cases.

Free-function: g_free

Fields#

class Structure

name#

type#: The GType of a structure

Structure#

The serialization format#

Constructors#

Methods#

Fields#

This Page