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 <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
:obj:`~gi.repository.Gst.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` 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 notNone
, 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 givenname
.See
set_name()
for constraints on thename
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 notNone
, 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 theserialize()
function is used (withoutGST_SERIALIZE_FLAG_BACKWARD_COMPAT
)Free-function: gst_structure_free
Added in version 1.2.
- Parameters:
string – a string representation of a
Structure
Methods
- class Structure
- can_intersect(struct2: Structure) bool
Tries intersecting
struct1
andstruct2
and reports whether the result would not be empty.- Parameters:
struct2 – a
Structure
- filter_and_map_in_place(func: Callable[[...], bool], *user_data: Any) None
Calls the provided function once for each field in the
Structure
. In contrast toforeach()
, the function may modify the fields. In contrast tomap_in_place()
, the field is removed from the structure ifFalse
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
usingvalue_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 givenfield_name
field to the giventarget
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 totarget
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 totarget_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 totarget
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 givenfield_name
field to the giventarget
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[[...], bool], *user_data: Any) bool
Calls the provided function once for each field in the
Structure
. The function must not modify the fields. Also seemap_in_place()
andfilter_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 allocatedValueArray
and return it througharray
. Be aware that this is slower then getting theValue
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 withfree()
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 withunref()
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: type) 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) type
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: type) 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
andvalue_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 byvalue
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 througharray
. Be aware that this is slower then getting theValue
directly.Added in version 1.12.
- Parameters:
fieldname – the name of a field
- 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
guint64
pointed to byvalue
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) Any | 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 namedfieldname
.- Parameters:
fieldname – the name of a field
- has_field_typed(fieldname: str, type: type) bool
Check if
structure
contains a field namedfieldname
and with GTypetype
.- 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) Any | 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 namedfield
.- Parameters:
field –
Quark
of the field name
- id_has_field_typed(field: int, type: type) bool
Check if
structure
contains a field namedfield
and with GTypetype
.- Parameters:
field –
Quark
of the field nametype – the type of a value
- id_set_value(field: int, value: Any) None
Sets the field with the given GQuark
field
tovalue
. 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 fieldvalue – the new value of the field
- id_take_value(field: int, value: Any) None
Sets the field with the given GQuark
field
tovalue
. 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 fieldvalue – the new value of the field
- intersect(struct2: Structure) Structure | None
Intersects
struct1
andstruct2
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 ofsuperset
, i.e. has the same structure name and for all fields that are existing insuperset
,subset
has a value that is a subset of the value insuperset
.- Parameters:
superset – a potentially greater
Structure
- map_in_place(func: Callable[[...], bool], *user_data: Any) bool
Calls the provided function once for each field in the
Structure
. In contrast toforeach()
, 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
- 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_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 asflag
.Free-function: g_free
Added in version 1.20.
- 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 byfieldname
. Be aware that this is slower then using%GST_TYPE_ARRAY
in aValue
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 byfieldname
. Be aware that this is slower then using%GST_TYPE_LIST
in aValue
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 ofStructure
, 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: Any) None
Sets the field with the given name
field
tovalue
. 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
- take(newstr: Structure | None = None) tuple[bool, Structure]
Atomically modifies a pointer to point to a new structure. The
Structure
oldstr_ptr
is pointing to is freed andnewstr
is taken ownership over.Either
newstr
and the value pointed to byoldstr_ptr
may beNone
.It is a programming error if both
newstr
and the value pointed to byoldstr_ptr
refer to the same, non-None
structure.Added in version 1.18.
- Parameters:
newstr – a new
Structure
- take_value(fieldname: str, value: Any) None
Sets the field with the given name
field
tovalue
. 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 ofvalue
.- 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 userserialize()
instead for those cases.Free-function: g_free