Structure

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 must not be empty either, but may be NULL.

Last reviewed on 2012-03-29 (0.11.3)

class Structure {

GstStructure* gstStructure;

GstStructure* getStructureStruct();

void* getStruct();

this(GstStructure* gstStructure);

static Structure fromString(string name);

this(string name);

this(GQuark quark);

this(string name, string firstfield, void* varargs);

Structure copy();

string getName();

int hasName(string name);

void setName(string name);

GQuark getNameId();

int idGetValist(GQuark firstFieldId, void* args);

Value idGetValue(GQuark field);

void idSetValue(GQuark field, Value value);

void idTakeValue(GQuark field, Value value);

int getValist(string firstFieldname, void* args);

Value getValue(string fieldname);

void setValue(string fieldname, Value value);

void takeValue(string fieldname, Value value);

void setValist(string fieldname, void* varargs);

void idSetValist(GQuark fieldname, void* varargs);

void removeField(string fieldname);

void removeFieldsValist(string fieldname, void* varargs);

void removeAllFields();

GType getFieldType(string fieldname);

int foreac(GstStructureForeachFunc func, void* userData);

int nFields();

int hasField(string fieldname);

int hasFieldTyped(string fieldname, GType type);

int isEqual(Structure structure2);

int isSubset(Structure superset);

int canIntersect(Structure struct2);

Structure intersect(Structure struct2);

int idHasField(GQuark field);

int idHasFieldTyped(GQuark field, GType type);

int getBoolean(string fieldname, int value);

int getInt(string fieldname, int value);

int getUint(string fieldname, uint value);

int getDouble(string fieldname, double value);

string getString(string fieldname);

int getDate(string fieldname, Date value);

int getDateTime(string fieldname, DateTime value);

int getClockTime(string fieldname, GstClockTime value);

int getEnum(string fieldname, GType enumtype, int value);

int getFraction(string fieldname, int valueNumerator, int valueDenominator);

int mapInPlace(GstStructureMapFunc func, void* userData);

string nthFieldName(uint index);

int setParentRefcount(int* refcount);

string toString();

static Structure fromString(string string, string end);

void fixate();

int fixateField(string fieldName);

int fixateFieldNearestInt(string fieldName, int target);

int fixateFieldNearestDouble(string fieldName, double target);

int fixateFieldNearestFraction(string fieldName, int targetNumerator, int targetDenominator);

int fixateFieldBoolean(string fieldName, int target);

int fixateFieldString(string fieldName, string target);

}

Constructors

this this(GstStructure* gstStructure): Sets our main struct and passes it to the parent class
this this(string name): Creates a new, empty GstStructure with the given name. See gst_structure_set_name() for constraints on the name parameter. Free-function: gst_structure_free
this this(GQuark quark): Creates a new, empty GstStructure with the given name as a GQuark. Free-function: gst_structure_free
this this(string name, string firstfield, void* varargs): Creates a new GstStructure with the given name. Structure fields are set according to the varargs in a manner similar to gst_structure_new(). See gst_structure_set_name() for constraints on the name parameter. Free-function: gst_structure_free

Members

Functions

canIntersect int canIntersect(Structure struct2): Tries intersecting struct1 and struct2 and reports whether the result would not be empty.
copy Structure copy(): Duplicates a GstStructure and all its fields and values. Free-function: gst_structure_free
fixate void fixate(): Fixate all values in structure using gst_value_fixate(). structure will be modified in-place and should be writable.
fixateField int fixateField(string fieldName): Fixates a GstStructure by changing the given field with its fixated value.
fixateFieldBoolean int fixateFieldBoolean(string fieldName, int target): Fixates a GstStructure by changing the given field_name field to the given target boolean if that field is not fixed yet.
fixateFieldNearestDouble int fixateFieldNearestDouble(string fieldName, double target): Fixates a GstStructure by changing the given field to the nearest double to target that is a subset of the existing field.
fixateFieldNearestFraction int fixateFieldNearestFraction(string fieldName, int targetNumerator, int targetDenominator): Fixates a GstStructure by changing the given field to the nearest fraction to target_numerator/target_denominator that is a subset of the existing field.
fixateFieldNearestInt int fixateFieldNearestInt(string fieldName, int target): Fixates a GstStructure by changing the given field to the nearest integer to target that is a subset of the existing field.
fixateFieldString int fixateFieldString(string fieldName, string target): Fixates a GstStructure by changing the given field_name field to the given target string if that field is not fixed yet.
foreac int foreac(GstStructureForeachFunc func, void* userData): Calls the provided function once for each field in the GstStructure. The function must not modify the fields. Also see gst_structure_map_in_place().
free void free(): Frees a GstStructure and all its fields and values. The structure must not have a parent when this function is called.
getBoolean int getBoolean(string fieldname, int value): 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.
getClockTime int getClockTime(string fieldname, GstClockTime value): 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.
getDate int getDate(string fieldname, Date value): 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).
getDateTime int getDateTime(string fieldname, DateTime value): 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).
getDouble int getDouble(string fieldname, double value): 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.
getEnum int getEnum(string fieldname, GType enumtype, int value): 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.
getFieldType GType getFieldType(string fieldname): 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.
getFraction int getFraction(string fieldname, int valueNumerator, int valueDenominator): 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.
getInt int getInt(string fieldname, int value): 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.
getName string getName(): Get the name of structure as a string.
getNameId GQuark getNameId(): Get the name of structure as a GQuark.
getString string getString(string fieldname): 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.
getStruct void* getStruct(): the main Gtk struct as a void*
getStructureStruct GstStructure* getStructureStruct(): Get the main Gtk struct
getUint int getUint(string fieldname, uint value): 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.
getValist int getValist(string firstFieldname, void* args): Parses the variable arguments and reads fields from structure accordingly. valist-variant of gst_structure_get(). Look at the documentation of gst_structure_get() for more details.
getValue Value getValue(string fieldname): Get the value of the field with name fieldname.
hasField int hasField(string fieldname): Check if structure contains a field named fieldname.
hasFieldTyped int hasFieldTyped(string fieldname, GType type): Check if structure contains a field named fieldname and with GType type.
hasName int hasName(string name): Checks if the structure has the given name
idGetValist int idGetValist(GQuark firstFieldId, void* args): Parses the variable arguments and reads fields from structure accordingly. valist-variant of gst_structure_id_get(). Look at the documentation of gst_structure_id_get() for more details.
idGetValue Value idGetValue(GQuark field): Get the value of the field with GQuark field.
idHasField int idHasField(GQuark field): Check if structure contains a field named field.
idHasFieldTyped int idHasFieldTyped(GQuark field, GType type): Check if structure contains a field named field and with GType type.
idSetValist void idSetValist(GQuark fieldname, void* varargs): va_list form of gst_structure_id_set().
idSetValue void idSetValue(GQuark field, Value value): 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.
idTakeValue void idTakeValue(GQuark field, Value value): 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.
intersect Structure intersect(Structure struct2): Interesects struct1 and struct2 and returns the intersection.
isEqual int isEqual(Structure structure2): Tests if the two GstStructure are equal.
isSubset int isSubset(Structure superset): 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.
mapInPlace int mapInPlace(GstStructureMapFunc func, void* userData): Calls the provided function once for each field in the GstStructure. In contrast to gst_structure_foreach(), the function may modify but not delete the fields. The structure must be mutable.
nFields int nFields(): Get the number of fields in the structure.
nthFieldName string nthFieldName(uint index): Get the name of the given field number, counting from 0 onwards.
removeAllFields void removeAllFields(): Removes all fields in a GstStructure.
removeField void removeField(string fieldname): Removes the field with the given name. If the field with the given name does not exist, the structure is unchanged.
removeFieldsValist void removeFieldsValist(string fieldname, void* varargs): va_list form of gst_structure_remove_fields().
setName void setName(string name): 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 "/-_.:".
setParentRefcount int setParentRefcount(int* refcount): Sets the parent_refcount field of GstStructure. 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 GstStructure, as described in the MT Refcounting section of the design documents.
setValist void setValist(string fieldname, void* varargs): va_list form of gst_structure_set().
setValue void setValue(string fieldname, Value value): 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.
takeValue void takeValue(string fieldname, Value value): 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.
toString string toString(): Converts structure to a human-readable string representation.

Static functions

fromString Structure fromString(string name): Undocumented in source. Be warned that the author may not have intended to support it.
fromString Structure fromString(string string, string end): Creates a GstStructure from a string representation. If end is not NULL, a pointer to the place inside the given string where parsing ended will be returned. Free-function: gst_structure_free

Variables

gstStructure GstStructure* gstStructure;: the main Gtk struct

Meta

Source

See Implementation

gstreamer Structure classes

Structure