Structure

Object Hierarchy:

Description:

[ Immutable ]
public class Structure

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 folled by letters, numbers and any of "/-_.:". Structure is used by various GStreamer subsystems to store information in a flexible and extensible way. A Structure does not have a refcount because it usually is part of a higher level object such as Caps. It provides a means to enforce mutability using the refcount of the parent with the set_parent_refcount method. A Structure can be created with Structure.empty or Structure, 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_value or set. Field values can be retrieved with get_value or the more convenient gst_structure_get_*() functions. Fields can be removed with remove_field or 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 2009-06-08 (0.10.23)

Namespace: Gst

Package: gstreamer-0.10

Content:

Static methods:

public static Structure? from_string (string str, out string end)
Creates a Structure from a string representation. If end is not NULL, a pointer to the place inside the given string where parsing ended will be returned. not be parsed. Free with gst_structure_free after use.

Creation methods:

public Structure (string name, string firstfield, ...)
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. Last variable argument should be NULL.
public Structure.empty (string name)
Creates a new, empty Structure with the given name. See set_name for constraints on the name parameter.
public Structure.id (Quark quark, Quark field_quark, ...)
Creates a new Structure with the given name as a GQuark, followed by fieldname quark, GType, argument(s) "triplets" in the same format as id_set. Basically a convenience wrapper around Structure.id_empty and id_set. The last variable argument must be NULL (or 0).
public Structure.id_empty (Quark quark)
Creates a new, empty Structure with the given name as a GQuark.
public Structure.valist (string name, string firstfield, va_list varargs)
Creates a new Structure with the given name. Structure fields are set according to the varargs in a manner similar to Structure. See set_name for constraints on the name parameter.

Methods:

public bool can_intersect (Structure struct2)
public Structure copy ()
Duplicates a Structure and all its fields and values.
public bool fixate_field_boolean (string field_name, bool target)
Fixates a Structure by changing the given field_name field to the given
public bool fixate_field_nearest_double (string field_name, double target)
Fixates a Structure by changing the given field to the nearest double to target that is a subset of the existing field.
public bool fixate_field_nearest_fraction (string field_name, int target_numerator, int target_denominator)
Fixates a Structure by changing the given field to the nearest fraction to target_numerator/@target_denominator that is a subset of the existing field.
public bool fixate_field_nearest_int (string field_name, int target)
Fixates a Structure by changing the given field to the nearest integer to target that is a subset of the existing field.
public bool fixate_field_string (string field_name, string target)
Fixates a Structure by changing the given field_name field to the given
public bool foreach (StructureForeachFunc func)
Calls the provided function once for each field in the Structure. The function must not modify the fields. Also see map_in_place. FALSE otherwise.
public bool get (...)
Parses the variable arguments and reads fields from structure accordingly. Variable arguments should be in the form field name, field type (as a GType), pointer(s) to a variable(s) to hold the return value(s). The last variable argument should be NULL. For refcounted (mini)objects you will acquire your own reference which you must release with a suitable _unref() when no longer needed. For strings and boxed types you will acquire a copy which you will need to release with either g_free or the suiteable function for the boxed type. because the field requested did not exist, or was of a type other than the type specified), otherwise TRUE.
public bool get_boolean (string fieldname, out bool 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. with fieldname or the existing field did not contain a boolean, this function returns FALSE.
public bool get_clock_time (string fieldname, out ClockTime 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. with fieldname or the existing field did not contain a ClockTime, this function returns FALSE.
public bool get_date (string fieldname, out 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 inconsistent with e.g. get_string which doesn't return a copy of the string). with fieldname or the existing field did not contain a data, this function returns FALSE.
public bool get_date_time (string fieldname, out 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. get_string which doesn't return a copy of the string). with fieldname or the existing field did not contain a data, this function returns FALSE.
public bool get_double (string fieldname, out 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. with fieldname or the existing field did not contain a double, this function returns FALSE.
public bool get_enum (string fieldname, Type enumtype, out 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. with fieldname or the existing field did not contain an enum of the given type, this function returns FALSE.
public Type get_field_type (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.
public bool get_fourcc (string fieldname, out uint32 value)
Sets the Fourcc 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. with fieldname or the existing field did not contain a fourcc, this function returns FALSE.
public bool get_fraction (string fieldname, out int value_numerator, out int value_denominator)
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. with fieldname or the existing field did not contain a GstFraction, this function returns FALSE.
public bool get_int (string fieldname, out 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. with fieldname or the existing field did not contain an int, this function returns false.
public unowned string get_name ()
Get the name of structure as a string.
public Quark get_name_id ()
Get the name of structure as a GQuark.
public unowned string? get_string (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. or did not contain a string.
public bool get_uint (string fieldname, out 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. with fieldname or the existing field did not contain a uint, this function returns false.
public bool get_valist (string first_fieldname, va_list args)
Parses the variable arguments and reads fields from structure accordingly. valist-variant of get. Look at the documentation of get for more details.
public unowned Value? get_value (string fieldname)
Get the value of the field with name fieldname.
public bool has_field (string fieldname)
Check if structure contains a field named fieldname.
public bool has_field_typed (string fieldname, Type type)
Check if structure contains a field named fieldname and with GType type.
public bool has_name (string name)
Checks if the structure has the given name
public bool id_get (...)
Parses the variable arguments and reads fields from structure accordingly. Variable arguments should be in the form field id quark, field type (as a GType), pointer(s) to a variable(s) to hold the return value(s). The last variable argument should be NULL (technically it should be a 0 quark, but we require NULL so compilers that support it can check for the NULL terminator and warn if it's not there). This function is just like get only that it is slightly more efficient since it saves the string-to-quark lookup in the global quark hashtable. For refcounted (mini)objects you will acquire your own reference which you must release with a suitable _unref() when no longer needed. For strings and boxed types you will acquire a copy which you will need to release with either g_free or the suiteable function for the boxed type. because the field requested did not exist, or was of a type other than the type specified), otherwise TRUE.
public bool id_get_valist (Quark first_field_id, va_list args)
Parses the variable arguments and reads fields from structure accordingly. valist-variant of id_get. Look at the documentation of id_get for more details.
public unowned Value? id_get_value (Quark field)
Get the value of the field with GQuark field. identifier.
public bool id_has_field (Quark field)
Check if structure contains a field named field.
public bool id_has_field_typed (Quark field, Type type)
Check if structure contains a field named field and with GType type.
public void id_set (Quark fieldname, ...)
Identical to gst_structure_set, except that field names are passed using the GQuark for the field name. This allows more efficient setting of the structure if the caller already knows the associated quark values. The last variable argument must be NULL.
public void id_set_valist (Quark fieldname, va_list varargs)
va_list form of id_set.
public void id_set_value (Quark 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.
public void id_take_value (Quark 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.
public unowned Structure intersect (Structure struct2)
public bool is_equal (Structure structure2)
public bool is_subset (Structure superset)
public bool map_in_place (StructureMapFunc func)
Calls the provided function once for each field in the Structure. In contrast to foreach, the function may modify but not delete the fields. The structure must be mutable. FALSE otherwise.
public int n_fields ()
Get the number of fields in the structure.
public unowned string nth_field_name (uint index)
Get the name of the given field number, counting from 0 onwards.
public void remove_all_fields ()
Removes all fields in a GstStructure.
public void remove_field (string fieldname)
Removes the field with the given name. If the field with the given name does not exist, the structure is unchanged.
public void remove_fields (string fieldname, ...)
Removes the fields with the given names. If a field does not exist, the argument is ignored.
public void remove_fields_valist (string fieldname, va_list varargs)
va_list form of remove_fields.
public void set (string fieldname, ...)
Parses the variable arguments and sets fields accordingly. Variable arguments should be in the form field name, field type (as a GType), value(s). The last variable argument should be NULL.
public void set_name (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 "/-_.:".
public void set_parent_refcount (ref int refcount)
Sets the parent_refcount field of 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 Structure, as described in the MT Refcounting section of the design documents.
public void set_valist (string fieldname, va_list varargs)
va_list form of set.
public void set_value (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.
public void take_value (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.
public string to_string ()
Converts structure to a human-readable string representation. For debugging purposes its easier to do something like this: