org.freedesktop.gstreamer

Class Structure

java.lang.Object

org.freedesktop.gstreamer.glib.NativeObject

org.freedesktop.gstreamer.Structure

All Implemented Interfaces:

AutoCloseable

public class Structure
extends NativeObject

Generic structure containing fields of names and values.

See upstream documentation at https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstStructure.html

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 followed by letters, numbers and any of "/-_.:".

Structure is used by various GStreamer subsystems to store information in a flexible and extensible way.

A Structure can be created with new Structure(String) or Structure(String, String, Object...), 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{Integer,String}() etc functions.

Field values can be retrieved with get{Integer,String}() etc functions.

Fields can be removed with removeField(java.lang.String) or removeFields(java.lang.String...)

See Also:

Caps, Event

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	Structure.InvalidFieldException

Nested classes/interfaces inherited from class org.freedesktop.gstreamer.glib.NativeObject

NativeObject.Initializer, NativeObject.TypeProvider, NativeObject.TypeRegistration<T extends NativeObject>

Field Summary

Fields

Modifier and Type	Field and Description
static String	GTYPE_NAME

Constructor Summary

Constructors

Constructor and Description
Structure(String name) Creates a new, empty #GstStructure with the given name.
Structure(String name, String firstFieldName, Object... data) Creates a new Structure with the given name.

Method Summary

Modifier and Type	Method and Description
Structure	copy()
boolean	fixateNearestInteger(String field, Integer value)
static Structure	fromString(String data) Creates a Structure from a string representation.
boolean	getBoolean(String fieldName) Get the value of the named field as a boolean.
double	getDouble(String fieldName) Get the value of the named field as a double.
double[]	getDoubles(String fieldName) Extract the values of the named field as an array of doubles.
double[]	getDoubles(String fieldName, double[] array) Extract the values of the named field as an array of doubles.
int	getFields() Get the number of fields in the Structure.
int	getFourcc(String fieldName) Gets FOURCC field int representation
String	getFourccString(String fieldName) Gets FOURCC field String representation
Fraction	getFraction(String fieldName) Get the value of the named field as a Fraction.
int	getInteger(String fieldName) Get the value of the named field as an int.
int[]	getIntegers(String fieldName) Extract the values of the named field as an array of integers.
int[]	getIntegers(String fieldName, int[] array) Extract the values of the named field as an array of integers.
String	getName() Get the name of @structure as a string.
String	getName(int i) Get the @structure's ith field name as a string.
Range	getRange(String fieldName) Get the value of the named field as a Range.
String	getString(String fieldName) Get the value of the named field as a String.
Object	getValue(String fieldName) Get the value of the named field.
<T> List<T>	getValues(Class<T> type, String fieldName) Extract the values of the named field as a List of the provided type.
boolean	hasDoubleField(String fieldName) Check if the Structure contains a double field named fieldName.
boolean	hasField(String fieldName) Check if the Structure contains a field named fieldName.
boolean	hasField(String fieldName, Class<?> fieldType) Check if the Structure contains a field named fieldName.
boolean	hasIntField(String fieldName) Check if the Structure contains an integer field named fieldName.
boolean	hasName(String name) Checks if the structure has the given name.
boolean	isEqual(Structure structure) Checks that two structures are equal
void	removeField(String fieldName) Removes the field with the given name from the structure.
void	removeFields(String... fieldNames) Removes the fields with the given names.
void	setDouble(String field, Double value)
void	setDoubleRange(String field, Double min, Double max)
void	setFraction(String field, Integer numerator, Integer denominator)
void	setInteger(String field, Integer value) Sets an integer field in the structure.
void	setIntegerRange(String field, Integer min, Integer max)
void	setName(String name) Sets the name of the structure to the given name.
void	setObject(String field, String typeName, GObject object) Set an object field in the structure.
String	toString()

Methods inherited from class org.freedesktop.gstreamer.glib.NativeObject

close, disown, dispose, equals, getPointer, getRawPointer, hashCode, invalidate

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

GTYPE_NAME

public static final String GTYPE_NAME

See Also:

Constant Field Values

Constructor Detail

Structure

public Structure(String name)

Creates a new, empty #GstStructure with the given name.

Parameters:

name - The name of new structure.

Structure

public Structure(String name,
                 String firstFieldName,
                 Object... data)

Creates a new Structure with the given name. Parses the list of variable arguments and sets fields to the values listed. Variable arguments should be passed as field name, field type, and value.

Parameters:

name - The name of new structure.

firstFieldName - The name of first field to set

data - Additional arguments.

Method Detail

copy

public Structure copy()

fixateNearestInteger

public boolean fixateNearestInteger(String field,
                                    Integer value)

getBoolean

public boolean getBoolean(String fieldName)

Get the value of the named field as a boolean. Throws Structure.InvalidFieldException if the Structure does not contain the named field or the named field is not a boolean.

Parameters:

fieldName - name of field

Returns:

boolean value of the named field

getDouble

public double getDouble(String fieldName)

Get the value of the named field as a double. Throws Structure.InvalidFieldException if the Structure does not contain the named field or the named field is not a double.

Parameters:

fieldName - name of field

Returns:

double value of the named field

getDoubles

public double[] getDoubles(String fieldName)

Extract the values of the named field as an array of doubles. If the native GType of the field is a GValueArray then this method will return an array of the contained values, assuming all contained values are of G_TYPE_DOUBLE. Else if the field is of G_TYPE_DOUBLE a single value array will be returned.

This method will create a new array each time. If you are repeatedly calling this method consider using getDoubles(java.lang.String, double[]).

Throws Structure.InvalidFieldException if the field does not exist, or the field values contained are not of type G_TYPE_DOUBLE.

This method only currently supports lists of values inside a GValueArray - other native list types will be supported in future.

Parameters:

fieldName - name of field

Returns:

List of values from the named field

getDoubles

public double[] getDoubles(String fieldName,
                           double[] array)

Extract the values of the named field as an array of doubles. If the native GType of the field is a GValueArray then this method will return an array of the contained values, assuming all contained values are of G_TYPE_DOUBLE. Else if the field is of G_TYPE_DOUBLE a single value array will be returned.

An array may be passed into this method to contain the result. A new array will be created if the array is null or not of the correct length.

Throws Structure.InvalidFieldException if the field does not exist, or the field values contained are not of type G_TYPE_DOUBLE.

This method only currently supports lists of values inside a GValueArray - other native list types will be supported in future.

Parameters:

fieldName - name of field

array - an array to hold values, or null

Returns:

List of values from the named field

getFields

public int getFields()

Get the number of fields in the Structure.

Returns:

the structure's filed number.

getFourcc

public int getFourcc(String fieldName)

Gets FOURCC field int representation

Parameters:

fieldName - The name of the field.

Returns:

FOURCC field as a 4 byte integer

getFourccString

public String getFourccString(String fieldName)

Gets FOURCC field String representation

Parameters:

fieldName - The name of the field.

Returns:

FOURCC field as a String

getFraction

public Fraction getFraction(String fieldName)

Get the value of the named field as a Fraction. Throws Structure.InvalidFieldException if the Structure does not contain the named field or the named field is not a Fraction.

Parameters:

fieldName - name of field

Returns:

boolean value of the named field

getInteger

public int getInteger(String fieldName)

Get the value of the named field as an int. Throws Structure.InvalidFieldException if the Structure does not contain the named field or the named field is not an integer.

Parameters:

fieldName - name of field

Returns:

int value of the named field

getIntegers

public int[] getIntegers(String fieldName)

Extract the values of the named field as an array of integers. If the native GType of the field is a GValueArray then this method will return an array of the contained values, assuming all contained values are of G_TYPE_INT. Else if the field is of G_TYPE_INT a single value array will be returned.

This method will create a new array each time. If you are repeatedly calling this method consider using getIntegers(java.lang.String, int[]).

Throws Structure.InvalidFieldException if the field does not exist, or the field values contained are not of type G_TYPE_INT.

This method only currently supports lists of values inside a GValueArray - other native list types will be supported in future.

Parameters:

fieldName - name of field

Returns:

List of values from the named field

getIntegers

public int[] getIntegers(String fieldName,
                         int[] array)

Extract the values of the named field as an array of integers. If the native GType of the field is a GValueArray then this method will return an array of the contained values, assuming all contained values are of G_TYPE_INT. Else if the field is of G_TYPE_INT a single value array will be returned.

An array may be passed into this method to contain the result. A new array will be created if the array is null or not of the correct length.

Throws Structure.InvalidFieldException if the field does not exist, or the field values contained are not of type G_TYPE_INT.

This method only currently supports lists of values inside a GValueArray - other native list types will be supported in future.

Parameters:

fieldName - name of field

array - an array to hold values, or null

Returns:

List of values from the named field

setName

public void setName(String name)

Sets the name of the structure to the given name. The name must not be empty, must start with a letter and can be followed by letters, numbers and any of "/-_.:".

Parameters:

name - The new name of the structure.

getName

public String getName()

Get the name of @structure as a string.

Returns:

The name of the structure.

getName

public String getName(int i)

Get the @structure's ith field name as a string.

Parameters:

i - the requested filed number

Returns:

The name of the structure.

getRange

public Range getRange(String fieldName)

Get the value of the named field as a Range. Throws Structure.InvalidFieldException if the Structure does not contain the named field.

Parameters:

fieldName - name of field

Returns:

Range value of the named field

getString

public String getString(String fieldName)

Get the value of the named field as a String.

Parameters:

fieldName - name of field

Returns:

String value of the named field

getValue

public Object getValue(String fieldName)

Get the value of the named field. Throws Structure.InvalidFieldException if the Structure does not contain the named field.

Parameters:

fieldName - name of field

Returns:

Object representation of the named field

getValues

public <T> List<T> getValues(Class<T> type,
                             String fieldName)

Extract the values of the named field as a List of the provided type. If the native GType of the field is a GValueArray then this method will return a list of the contained values, assuming all contained values can be converted to the provided Java type T. Else if the field GType can be directly converted to the provided Java type T, a singleton List will be returned.

Throws Structure.InvalidFieldException if the field does not exist, or the field values cannot be converted to type T.

This method currently supports lists of values inside a GValueArray or GstValueList.

Type Parameters:

T -

Parameters:

type - type of values

fieldName - name of field

Returns:

List of values from the named field

hasDoubleField

public boolean hasDoubleField(String fieldName)

Check if the Structure contains a double field named fieldName.

Parameters:

fieldName - The name of the field to check.

Returns:

true if the structure contains a double field named fieldName

hasField

public boolean hasField(String fieldName)

Check if the Structure contains a field named fieldName.

Parameters:

fieldName - The name of the field to check.

Returns:

true if the structure contains a field with the given name.

hasField

public boolean hasField(String fieldName,
                        Class<?> fieldType)

Check if the Structure contains a field named fieldName.

Parameters:

fieldName - The name of the field to check.

fieldType - The type of the field.

Returns:

true if the structure contains a field named fieldName and of type fieldType

hasIntField

public boolean hasIntField(String fieldName)

Check if the Structure contains an integer field named fieldName.

Parameters:

fieldName - The name of the field to check.

Returns:

true if the structure contains an integer field named fieldName

hasName

public boolean hasName(String name)

Checks if the structure has the given name.

Parameters:

name - structure name to check for

Returns:

true if @name matches the name of the structure.

isEqual

public boolean isEqual(Structure structure)

Checks that two structures are equal

Parameters:

structure - the structure to check if it's equal to this structure

Returns:

true if both structures are equal

removeField

public void removeField(String fieldName)

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

Parameters:

fieldName - The name of the field to remove.

removeFields

public void removeFields(String... fieldNames)

Removes the fields with the given names. If a field does not exist, the argument is ignored.

Parameters:

fieldNames - A list of field names to remove.

setDouble

public void setDouble(String field,
                      Double value)

setDoubleRange

public void setDoubleRange(String field,
                           Double min,
                           Double max)

setFraction

public void setFraction(String field,
                        Integer numerator,
                        Integer denominator)

setInteger

public void setInteger(String field,
                       Integer value)

Sets an integer field in the structure.

Parameters:

field - the name of the field to set.

value - the value to set for the field.

setIntegerRange

public void setIntegerRange(String field,
                            Integer min,
                            Integer max)

setObject

public void setObject(String field,
                      String typeName,
                      GObject object)

Set an object field in the structure.

Parameters:

field - the name of the field to set.

typeName - a type into which the provided object could be coerced into.

object - the value to set for the field (must not be null).

toString

public String toString()

Overrides:

toString in class NativeObject

fromString

public static Structure fromString(String data)

Creates a Structure from a string representation.

Parameters:

data - A string representation of a Structure.

Returns:

A new Structure or null when the string could not be parsed.