:right-sidebar: True Structure =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Structure(*args, **kwargs) :no-contents-entry: A :obj:`~gi.repository.Gst.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 :obj:`~gi.repository.Gst.Structure` also has a name. The name starts with a letter and can be filled by letters, numbers and any of "/-_.:". :obj:`~gi.repository.Gst.Structure` is used by various GStreamer subsystems to store information in a flexible and extensible way. A :obj:`~gi.repository.Gst.Structure` does not have a refcount because it usually is part of a higher level object such as :obj:`~gi.repository.Gst.Caps`\, :obj:`~gi.repository.Gst.Message`\, :obj:`~gi.repository.Gst.Event`\, :obj:`~gi.repository.Gst.Query`\. It provides a means to enforce mutability using the refcount of the parent with the :func:`~gi.repository.Gst.Structure.set_parent_refcount` method. A :obj:`~gi.repository.Gst.Structure` can be created with :func:`~gi.repository.Gst.Structure.new_empty` or :func:`~gi.repository.Gst.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 :func:`~gi.repository.Gst.Structure.set_value` or :func:`~gi.repository.Gst.Structure.set`. Field values can be retrieved with :func:`~gi.repository.Gst.Structure.get_value` or the more convenient ``gst_structure_get_*()`` functions. Fields can be removed with :func:`~gi.repository.Gst.Structure.remove_field` or :func:`~gi.repository.Gst.Structure.remove_fields`. Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not allowed. Strings may be :const:`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: .. code-block:: :dedent: 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: .. code-block:: :dedent: 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 :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: .. code-block:: :dedent: a-struct, special="\"{[(;)]}\" can be used inside quotes" They also allow for nested structure, such as: .. code-block:: :dedent: a-struct, nested=(GstStructure)"nested-struct, nested=true" Since 1.20, nested structures and caps can be specified using brackets (``[`` and ``]``\), for example: .. code-block:: :dedent: 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 ------------ .. rst-class:: interim-class .. class:: Structure :no-index: .. classmethod:: from_string(string: str) -> ~typing.Tuple[~gi.repository.Gst.Structure | None, str] Creates a :obj:`~gi.repository.Gst.Structure` from a string representation. If end is not :const:`None`, a pointer to the place inside the given string where parsing ended will be returned. Free-function: gst_structure_free :param string: a string representation of a :obj:`~gi.repository.Gst.Structure`\. .. classmethod:: new_empty(name: str) -> ~gi.repository.Gst.Structure Creates a new, empty :obj:`~gi.repository.Gst.Structure` with the given ``name``\. See :func:`~gi.repository.Gst.Structure.set_name` for constraints on the ``name`` parameter. Free-function: gst_structure_free :param name: name of new structure .. classmethod:: new_from_string(string: str) -> ~gi.repository.Gst.Structure | None Creates a :obj:`~gi.repository.Gst.Structure` from a string representation. If end is not :const:`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 :obj:`~gi.repository.Gst.Caps` / :obj:`~gi.repository.Gst.Structure` deeper than one level unless the :func:`~gi.repository.Gst.Structure.serialize` function is used (without ``GST_SERIALIZE_FLAG_BACKWARD_COMPAT``) Free-function: gst_structure_free .. versionadded:: 1.2 :param string: a string representation of a :obj:`~gi.repository.Gst.Structure` .. classmethod:: new_id_empty(quark: int) -> ~gi.repository.Gst.Structure Creates a new, empty :obj:`~gi.repository.Gst.Structure` with the given name as a GQuark. Free-function: gst_structure_free :param quark: name of new structure Methods ------- .. rst-class:: interim-class .. class:: Structure :no-index: .. method:: can_intersect(struct2: ~gi.repository.Gst.Structure) -> bool Tries intersecting ``struct1`` and ``struct2`` and reports whether the result would not be empty. :param struct2: a :obj:`~gi.repository.Gst.Structure` .. method:: filter_and_map_in_place(func: ~typing.Callable[[int, ~gi.repository.GObject.Value, ~typing.Any], bool], user_data: ~typing.Any = None) -> None Calls the provided function once for each field in the :obj:`~gi.repository.Gst.Structure`\. In contrast to :func:`~gi.repository.Gst.Structure.foreach`, the function may modify the fields. In contrast to :func:`~gi.repository.Gst.Structure.map_in_place`, the field is removed from the structure if :const:`False` is returned from the function. The structure must be mutable. .. versionadded:: 1.6 :param func: a function to call for each field :param user_data: private data .. method:: fixate() -> None Fixate all values in ``structure`` using :func:`~gi.repository.Gst.value_fixate`. ``structure`` will be modified in-place and should be writable. .. method:: fixate_field(field_name: str) -> bool Fixates a :obj:`~gi.repository.Gst.Structure` by changing the given field with its fixated value. :param field_name: a field in ``structure`` .. method:: fixate_field_boolean(field_name: str, target: bool) -> bool Fixates a :obj:`~gi.repository.Gst.Structure` by changing the given ``field_name`` field to the given ``target`` boolean if that field is not fixed yet. :param field_name: a field in ``structure`` :param target: the target value of the fixation .. method:: fixate_field_nearest_double(field_name: str, target: float) -> bool Fixates a :obj:`~gi.repository.Gst.Structure` by changing the given field to the nearest double to ``target`` that is a subset of the existing field. :param field_name: a field in ``structure`` :param target: the target value of the fixation .. method:: fixate_field_nearest_fraction(field_name: str, target_numerator: int, target_denominator: int) -> bool Fixates a :obj:`~gi.repository.Gst.Structure` by changing the given field to the nearest fraction to ``target_numerator``\/``target_denominator`` that is a subset of the existing field. :param field_name: a field in ``structure`` :param target_numerator: The numerator of the target value of the fixation :param target_denominator: The denominator of the target value of the fixation .. method:: fixate_field_nearest_int(field_name: str, target: int) -> bool Fixates a :obj:`~gi.repository.Gst.Structure` by changing the given field to the nearest integer to ``target`` that is a subset of the existing field. :param field_name: a field in ``structure`` :param target: the target value of the fixation .. method:: fixate_field_string(field_name: str, target: str) -> bool Fixates a :obj:`~gi.repository.Gst.Structure` by changing the given ``field_name`` field to the given ``target`` string if that field is not fixed yet. :param field_name: a field in ``structure`` :param target: the target value of the fixation .. method:: foreach(func: ~typing.Callable[[int, ~gi.repository.GObject.Value, ~typing.Any], bool], user_data: ~typing.Any = None) -> bool Calls the provided function once for each field in the :obj:`~gi.repository.Gst.Structure`\. The function must not modify the fields. Also see :func:`~gi.repository.Gst.Structure.map_in_place` and :func:`~gi.repository.Gst.Structure.filter_and_map_in_place`. :param func: a function to call for each field :param user_data: private data .. method:: free() -> None Frees a :obj:`~gi.repository.Gst.Structure` and all its fields and values. The structure must not have a parent when this function is called. .. method:: get_array(fieldname: str) -> ~typing.Tuple[bool, ~gi.repository.GObject.ValueArray] This is useful in language bindings where unknown :obj:`~gi.repository.GObject.Value` types are not supported. This function will convert the %GST_TYPE_ARRAY into a newly allocated :obj:`~gi.repository.GObject.ValueArray` and return it through ``array``\. Be aware that this is slower then getting the :obj:`~gi.repository.GObject.Value` directly. .. versionadded:: 1.12 :param fieldname: the name of a field .. method:: get_boolean(fieldname: str) -> ~typing.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. :param fieldname: the name of a field .. method:: get_clock_time(fieldname: str) -> ~typing.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. :param fieldname: the name of a field .. method:: get_date(fieldname: str) -> ~typing.Tuple[bool, ~gi.repository.GLib.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 :func:`~gi.repository.GLib.Date.free` when no longer needed (note: this is inconsistent with e.g. :func:`~gi.repository.Gst.Structure.get_string` which doesn't return a copy of the string). :param fieldname: the name of a field .. method:: get_date_time(fieldname: str) -> ~typing.Tuple[bool, ~gi.repository.Gst.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 :func:`~gi.repository.Gst.DateTime.unref` when no longer needed (note: this is inconsistent with e.g. :func:`~gi.repository.Gst.Structure.get_string` which doesn't return a copy of the string). :param fieldname: the name of a field .. method:: get_double(fieldname: str) -> ~typing.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. :param fieldname: the name of a field .. method:: get_enum(fieldname: str, enumtype: ~gobject.GType) -> ~typing.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. :param fieldname: the name of a field :param enumtype: the enum type of a field .. method:: get_field_type(fieldname: str) -> ~gobject.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. :param fieldname: the name of the field .. method:: get_flags(fieldname: str, flags_type: ~gobject.GType) -> ~typing.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. .. versionadded:: 1.22 :param fieldname: the name of a field :param flags_type: the flags type of a field .. method:: get_flagset(fieldname: str) -> ~typing.Tuple[bool, int, int] Read the GstFlagSet flags and mask out of the structure into the provided pointers. .. versionadded:: 1.6 :param fieldname: the name of a field .. method:: get_fraction(fieldname: str) -> ~typing.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. :param fieldname: the name of a field .. method:: get_int(fieldname: str) -> ~typing.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. :param fieldname: the name of a field .. method:: get_int64(fieldname: str) -> ~typing.Tuple[bool, int] Sets the :obj:`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. .. versionadded:: 1.4 :param fieldname: the name of a field .. method:: get_list(fieldname: str) -> ~typing.Tuple[bool, ~gi.repository.GObject.ValueArray] This is useful in language bindings where unknown :obj:`~gi.repository.GObject.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 :obj:`~gi.repository.GObject.Value` directly. .. versionadded:: 1.12 :param fieldname: the name of a field .. method:: get_name() -> str Get the name of ``structure`` as a string. .. method:: get_name_id() -> int Get the name of ``structure`` as a GQuark. .. method:: 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. :param fieldname: the name of a field .. method:: get_uint(fieldname: str) -> ~typing.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. :param fieldname: the name of a field .. method:: get_uint64(fieldname: str) -> ~typing.Tuple[bool, int] Sets the :obj:`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. .. versionadded:: 1.4 :param fieldname: the name of a field .. method:: get_value(fieldname: str) -> ~gi.repository.GObject.Value | None Get the value of the field with name ``fieldname``\. :param fieldname: the name of the field to get .. method:: has_field(fieldname: str) -> bool Check if ``structure`` contains a field named ``fieldname``\. :param fieldname: the name of a field .. method:: has_field_typed(fieldname: str, type: ~gobject.GType) -> bool Check if ``structure`` contains a field named ``fieldname`` and with GType ``type``\. :param fieldname: the name of a field :param type: the type of a value .. method:: has_name(name: str) -> bool Checks if the structure has the given name :param name: structure name to check for .. method:: id_get_value(field: int) -> ~gi.repository.GObject.Value | None Get the value of the field with GQuark ``field``\. :param field: the :obj:`~gi.repository.GLib.Quark` of the field to get .. method:: id_has_field(field: int) -> bool Check if ``structure`` contains a field named ``field``\. :param field: :obj:`~gi.repository.GLib.Quark` of the field name .. method:: id_has_field_typed(field: int, type: ~gobject.GType) -> bool Check if ``structure`` contains a field named ``field`` and with GType ``type``\. :param field: :obj:`~gi.repository.GLib.Quark` of the field name :param type: the type of a value .. method:: id_set_value(field: int, value: ~gi.repository.GObject.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. :param field: a :obj:`~gi.repository.GLib.Quark` representing a field :param value: the new value of the field .. method:: id_take_value(field: int, value: ~gi.repository.GObject.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. :param field: a :obj:`~gi.repository.GLib.Quark` representing a field :param value: the new value of the field .. method:: intersect(struct2: ~gi.repository.Gst.Structure) -> ~gi.repository.Gst.Structure | None Intersects ``struct1`` and ``struct2`` and returns the intersection. :param struct2: a :obj:`~gi.repository.Gst.Structure` .. method:: is_equal(structure2: ~gi.repository.Gst.Structure) -> bool Tests if the two :obj:`~gi.repository.Gst.Structure` are equal. :param structure2: a :obj:`~gi.repository.Gst.Structure`\. .. method:: is_subset(superset: ~gi.repository.Gst.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``\. :param superset: a potentially greater :obj:`~gi.repository.Gst.Structure` .. method:: map_in_place(func: ~typing.Callable[[int, ~gi.repository.GObject.Value, ~typing.Any], bool], user_data: ~typing.Any = None) -> bool Calls the provided function once for each field in the :obj:`~gi.repository.Gst.Structure`\. In contrast to :func:`~gi.repository.Gst.Structure.foreach`, the function may modify but not delete the fields. The structure must be mutable. :param func: a function to call for each field :param user_data: private data .. method:: n_fields() -> int Get the number of fields in the structure. .. method:: nth_field_name(index: int) -> str Get the name of the given field number, counting from 0 onwards. :param index: the index to get the name of .. method:: remove_all_fields() -> None Removes all fields in a GstStructure. .. method:: 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. :param fieldname: the name of the field to remove .. method:: serialize(flags: ~gi.repository.Gst.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``\. :const:`~gi.repository.Gst.SerializeFlags.STRICT` flags is not allowed because it would make this function nullable which is an API break for bindings. Use :func:`~gi.repository.Gst.Structure.serialize_full` instead. Free-function: g_free .. versionadded:: 1.20 .. deprecated:: Unknown Use :func:`~gi.repository.Gst.Structure.serialize_full` instead. :param flags: The flags to use to serialize structure .. method:: serialize_full(flags: ~gi.repository.Gst.SerializeFlags) -> str | None Alias for :func:`~gi.repository.Gst.Structure.serialize` but with nullable annotation because it can return :const:`None` when :const:`~gi.repository.Gst.SerializeFlags.STRICT` flag is set. .. versionadded:: 1.24 :param flags: The flags to use to serialize structure .. method:: set_array(fieldname: str, array: ~gi.repository.GObject.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 :obj:`~gi.repository.GObject.Value` directly. .. versionadded:: 1.12 :param fieldname: the name of a field :param array: a pointer to a :obj:`~gi.repository.GObject.ValueArray` .. method:: set_list(fieldname: str, array: ~gi.repository.GObject.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 :obj:`~gi.repository.GObject.Value` directly. .. versionadded:: 1.12 :param fieldname: the name of a field :param array: a pointer to a :obj:`~gi.repository.GObject.ValueArray` .. method:: 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 "/-_.:". :param name: the new name of the structure .. method:: set_parent_refcount(refcount: int) -> bool Sets the parent_refcount field of :obj:`~gi.repository.Gst.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 :obj:`~gi.repository.Gst.Structure`\, as described in the MT Refcounting section of the design documents. :param refcount: a pointer to the parent's refcount .. method:: set_value(fieldname: str, value: ~gi.repository.GObject.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. :param fieldname: the name of the field to set :param value: the new value of the field .. classmethod:: take(newstr: ~gi.repository.Gst.Structure | None = None) -> ~typing.Tuple[bool, ~gi.repository.Gst.Structure | None] Atomically modifies a pointer to point to a new structure. The :obj:`~gi.repository.Gst.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 :const:`None`. It is a programming error if both ``newstr`` and the value pointed to by ``oldstr_ptr`` refer to the same, non-:const:`None` structure. .. versionadded:: 1.18 :param newstr: a new :obj:`~gi.repository.Gst.Structure` .. method:: take_value(fieldname: str, value: ~gi.repository.GObject.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``\. :param fieldname: the name of the field to set :param value: the new value of the field .. method:: to_string() -> str Converts ``structure`` to a human-readable string representation. For debugging purposes its easier to do something like this: |[ 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 :obj:`~gi.repository.Gst.Caps` / :obj:`~gi.repository.Gst.Structure` deeper than one level, you should user :func:`~gi.repository.Gst.Structure.serialize_full` instead for those cases. Free-function: g_free Fields ------ .. rst-class:: interim-class .. class:: Structure :no-index: .. attribute:: name .. attribute:: type The GType of a structure