Tries intersecting struct1 and struct2 and reports whether the result
would not be empty.
true if intersection would not be empty
Duplicates a Gst.Structure and all its fields and values.
Free-function: gst_structure_free
a new Gst.Structure.
Calls the provided function once for each field in the Gst.Structure. In
contrast to gst_structure_foreach(), the function may modify the fields.
In contrast to gst_structure_map_in_place(), the field is removed from
the structure if false is returned from the function.
The structure must be mutable.
a function to call for each field
Calls the provided function once for each field in the Gst.Structure. In
contrast to gst_structure_foreach_id_str(), the function may modify the fields.
In contrast to gst_structure_map_in_place_id_str(), the field is removed from
the structure if false is returned from the function.
The structure must be mutable.
a function to call for each field
Fixate all values in structure using gst_value_fixate().
structure will be modified in-place and should be writable.
Fixates a Gst.Structure by changing the given field with its fixated value.
a field in structure
true if the structure field could be fixated
Fixates a Gst.Structure by changing the given field_name field to the given
target boolean if that field is not fixed yet.
a field in structure
the target value of the fixation
true if the structure could be fixated
Fixates a Gst.Structure by changing the given field to the nearest
double to target that is a subset of the existing field.
a field in structure
the target value of the fixation
true if the structure could be fixated
Fixates a Gst.Structure by changing the given field to the nearest
fraction to target_numerator/target_denominator that is a subset
of the existing field.
a field in structure
The numerator of the target value of the fixation
The denominator of the target value of the fixation
true if the structure could be fixated
Fixates a Gst.Structure by changing the given field to the nearest
integer to target that is a subset of the existing field.
a field in structure
the target value of the fixation
true if the structure could be fixated
Fixates a Gst.Structure by changing the given field_name field to the given
target string if that field is not fixed yet.
a field in structure
the target value of the fixation
true if the structure could be fixated
Calls the provided function once for each field in the Gst.Structure. The
function must not modify the fields. Also see gst_structure_map_in_place()
and gst_structure_filter_and_map_in_place().
a function to call for each field
true if the supplied function returns true For each of the fields, false otherwise.
Calls the provided function once for each field in the Gst.Structure. The
function must not modify the fields. Also see gst_structure_map_in_place_id_str()
and gst_structure_filter_and_map_in_place_id_str().
a function to call for each field
true if the supplied function returns true For each of the fields, false otherwise.
Frees a Gst.Structure and all its fields and values. The structure must not have a parent when this function is called.
This is useful in language bindings where unknown GObject.Value types are not
supported. This function will convert the GST_TYPE_ARRAY into a newly
allocated GObject.ValueArray and return it through array. Be aware that this is
slower then getting the GObject.Value directly.
the name of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a GST_TYPE_ARRAY, this function returns false.
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.
the name of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a boolean, this function returns false.
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.
the name of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a Gst.ClockTime, this function returns false.
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 g_date_free() when no longer needed (note: this is
inconsistent with e.g. gst_structure_get_string() which doesn't return a
copy of the string).
the name of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a data, this function returns false.
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 gst_date_time_unref() when no longer needed
(note: this is inconsistent with e.g. gst_structure_get_string()
which doesn't return a copy of the string).
the name of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a data, this function returns false.
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.
the name of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a double, this function returns false.
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.
the name of a field
the enum type of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain an enum of the given type, this function returns false.
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.
the name of the field
the GObject.Value of the field
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.
the name of a field
the flags type of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain flags or did not contain flags of the given type, this function returns false.
Read the GstFlagSet flags and mask out of the structure into the provided pointers.
the name of a field
true if the values could be set correctly. If there was no field with fieldname or the existing field did not contain a GstFlagSet, this function returns false.
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.
the name of a field
true if the values could be set correctly. If there was no field with fieldname or the existing field did not contain a GstFraction, this function returns false.
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.
the name of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain an int, this function returns false.
Sets the gint64 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.
the name of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a gint64, this function returns false.
This is useful in language bindings where unknown 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 GObject.Value directly.
the name of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a GST_TYPE_LIST, this function returns false.
Get the name of structure as a string.
the name of the structure.
Get the name of structure as a GQuark.
the quark representing the name of the structure.
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.
the name of a field
a pointer to the string or null when the field did not exist or did not contain a string.
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.
the name of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a uint, this function returns false.
Sets the guint64 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.
the name of a field
true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a guint64, this function returns false.
Get the value of the field with name fieldname.
the name of the field to get
the GObject.Value corresponding to the field with the given name.
Check if structure contains a field named fieldname.
the name of a field
true if the structure contains a field with the given name
Check if structure contains a field named fieldname and with GType type.
the name of a field
the type of a value
true if the structure contains a field with the given name and type
Checks if the structure has the given name
structure name to check for
true if name matches the name of the structure.
Get the value of the field with GQuark field.
the GLib.Quark of the field to get
the GObject.Value corresponding to the field with the given name identifier.
Check if structure contains a field named field.
GLib.Quark of the field name
true if the structure contains a field with the given name
Check if structure contains a field named field and with GType type.
GLib.Quark of the field name
the type of a value
true if the structure contains a field with the given name and type
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.
a GLib.Quark representing a field
the new value of the field
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.
the name of the field
the GObject.Value of the field
Get the value of the field with name fieldname.
the name of the field to get
the GObject.Value corresponding to the field with the given name.
Check if structure contains a field named fieldname.
the name of a field
true if the structure contains a field with the given name
Get the name (as a GstIdStr) of the given field number, counting from 0 onwards.
the index to get the name of
the name of the given field number
Removes the field with the given name. If the field with the given name does not exist, the structure is unchanged.
the name of the field to remove
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 name of the field to set
the new value of the field
Sets the field with the given GstIdStr field to value. If the field
does not exist, it is created. If the field exists, the previous
value is replaced and freed.
the name of the field to set
the new value of the field
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.
a GLib.Quark representing a field
the new value of the field
Tests if the two Gst.Structure are equal.
true if the two structures have the same name and field.
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.
a potentially greater Gst.Structure
true if subset is a subset of superset
Checks if the structure is writable. true if parent
is not set or its refcount is 1, false otherwise.
true if the structure is writable.
Calls the provided function once for each field in the Gst.Structure. In
contrast to gst_structure_foreach(), the function may modify but not delete the
fields. The structure must be mutable.
a function to call for each field
true if the supplied function returns true For each of the fields, false otherwise.
Calls the provided function once for each field in the Gst.Structure. In
contrast to gst_structure_foreach_id_str(), the function may modify but not delete the
fields. The structure must be mutable.
a function to call for each field
true if the supplied function returns true For each of the fields, false otherwise.
Get the number of fields in the structure.
the number of fields in the structure
Get the name of the given field number, counting from 0 onwards.
the index to get the name of
the name of the given field number
Removes all fields in a GstStructure.
Removes the field with the given name. If the field with the given name does not exist, the structure is unchanged.
the name of the field to remove
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.
Gst.SerializeFlags.STRICT flags is not allowed because it would make this
function nullable which is an API break for bindings.
Use gst_structure_serialize_full() instead.
Free-function: g_free
The flags to use to serialize structure
a pointer to string allocated by g_malloc(). g_free() after usage.
Alias for gst_structure_serialize() but with nullable annotation because it
can return null when Gst.SerializeFlags.STRICT flag is set.
The flags to use to serialize structure
a pointer to string allocated by g_malloc(). g_free() after usage.
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 GObject.Value directly.
the name of a field
a pointer to a GObject.ValueArray
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 GObject.Value directly.
the name of a field
a pointer to a GObject.ValueArray
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 "/-_.:".
the new name of the structure
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 "/-_.:".
the new name of the structure
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 "/-_.:".
name needs to be valid for the remaining lifetime of the process, e.g. has
to be a static string.
the new name of the structure
Sets the parent_refcount field of 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 Gst.Structure, as described in the MT Refcounting section of the design documents.
a pointer to the parent's refcount
true if the parent refcount could be set.
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 name of the field to set
the new value of the field
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.
fieldname needs to be valid for the remaining lifetime of the process, e.g.
has to be a static string.
the name of the field to set
the new value of the field
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.
the name of the field to set
the new value of the field
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.
fieldname needs to be valid for the remaining lifetime of the process, e.g.
has to be a static string.
the name of the field to set
the new value of the field
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 Gst.Caps
/ Gst.Structure deeper than one level, you should user
gst_structure_serialize_full() instead for those cases.
Free-function: g_free
a pointer to string allocated by g_malloc(). g_free() after usage.
Staticfrom_Staticnew_Staticnew_Staticnew_Staticnew_Staticnew_StatictakeAtomically modifies a pointer to point to a new structure.
The 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 null.
It is a programming error if both newstr and the value pointed to by
oldstr_ptr refer to the same, non-null structure.
Optionaloldstr_ptr: Structurepointer to a place of a Gst.Structure to take
Optionalnewstr: Structurea new Gst.Structure
A 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 Gst.Structure also has a name. The name starts with a letter and can be filled by letters, numbers and any of "/-_.:".
Gst.Structure is used by various GStreamer subsystems to store information in a flexible and extensible way. A Gst.Structure does not have a refcount because it usually is part of a higher level object such as Gst.Caps, Gst.Message, Gst.Event, Gst.Query. It provides a means to enforce mutability using the refcount of the parent with the
gst_structure_set_parent_refcount()method.A Gst.Structure can be created with
gst_structure_new_empty()orgst_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_set_value()orgst_structure_set().Field values can be retrieved with
gst_structure_get_value()or the more convenient gst_structure_get_*() functions.Fields can be removed with
gst_structure_remove_field()orgst_structure_remove_fields().Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not allowed. Strings may be
nullhowever.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:The values type will be inferred if not explicitly specified with the
(GTypeName)valuesyntax, for example the following struct will have one field called 'is-string' which has the string 'true' as a value:Note: without specifying
(string),field-is-string` type would have been inferred as boolean.Note: we specified
(string)as a type even ifgchararrayis 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.
1is anintwhile1.0is adouble).Note: when a structure is serialized with
gst_structure_to_string, all values are explicitly typed.Some types have special delimiters:
<and>). For example `a-structure, array=<1, 2, 3>[and]). For examplea-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]{and}). For examplea-structure, list={1, 2, 3}<and>) and each string is double-quoted. For examplea-structure, strv=(GStrv)<"foo", "bar">. Since 1.26.0.Structures are delimited either by a null character
\0or a semicolon;the latter allowing to store multiple structures in the same string (see {@link 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:They also allow for nested structure, such as:
Since 1.20, nested structures and caps can be specified using brackets (
[and]), for example: