Package org.freedesktop.gstreamer.gst

Class Structure

java.lang.Object
io.github.jwharm.javagi.base.ProxyInstance
org.freedesktop.gstreamer.gst.Structure
All Implemented Interfaces:
Proxy
@Generated("io.github.jwharm.JavaGI") public class Structure extends ProxyInstance
A GstStructure 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 GstStructure also has a name. The name starts with a letter and can be filled by letters, numbers and any of "/-_.:".

GstStructure is used by various GStreamer subsystems to store information in a flexible and extensible way. A GstStructure does not have a refcount because it usually is part of a higher level object such as GstCaps, GstMessage, GstEvent, GstQuery. It provides a means to enforce mutability using the refcount of the parent with the gst_structure_set_parent_refcount() method.

A GstStructure can be created with gst_structure_new_empty() or 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 gst_structure_set_value() or gst_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() or gst_structure_remove_fields().

Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not allowed. Strings may be null 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: {@code 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 {@code }). 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 #GstCaps). 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 a-struct, special="\\"{[(;)]}\\" can be used inside quotes" } They also allow for nested structure, such as: {@code a-struct, nested=(GstStructure)"nested-struct, nested=true" } Since 1.20, nested structures and caps can be specified using brackets ([ and ]), for example: {@code a-struct, nested=[nested-struct, nested=true] }`

*note*: gst_structure_to_string() won't use that syntax for backward compatibility reason, gst_structure_serialize_full() has been added for that purpose.