GstStructure

typedef struct {
  GType type;
} GstStructure;

The GstStructure object. Most fields are private.

GstStructureForeachFunc ()

gboolean            (*GstStructureForeachFunc)          (GQuark field_id,
                                                         const GValue *value,
                                                         gpointer user_data);

A function that will be called in gst_structure_foreach(). The function may not modify value.

GstStructureMapFunc ()

gboolean            (*GstStructureMapFunc)              (GQuark field_id,
                                                         GValue *value,
                                                         gpointer user_data);

A function that will be called in gst_structure_map_in_place(). The function may modify value.

gst_structure_empty_new ()

GstStructure*       gst_structure_empty_new             (const gchar *name);

Creates a new, empty GstStructure with the given name.

See gst_structure_set_name() for constraints on the name parameter.

gst_structure_id_empty_new ()

GstStructure*       gst_structure_id_empty_new          (GQuark quark);

Creates a new, empty GstStructure with the given name as a GQuark.

gst_structure_new ()

GstStructure*       gst_structure_new                   (const gchar *name,
                                                         const gchar *firstfield,
                                                         ...);

Creates a new GstStructure 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.

gst_structure_new_valist ()

GstStructure*       gst_structure_new_valist            (const gchar *name,
                                                         const gchar *firstfield,
                                                         va_list 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.

gst_structure_id_new ()

GstStructure*       gst_structure_id_new                (GQuark name_quark,
                                                         GQuark field_quark,
                                                         ...);

Creates a new GstStructure with the given name as a GQuark, followed by fieldname quark, GType, argument(s) "triplets" in the same format as gst_structure_id_set(). Basically a convenience wrapper around gst_structure_id_empty_new() and gst_structure_id_set().

The last variable argument must be NULL (or 0).

Since 0.10.24

gst_structure_copy ()

GstStructure*       gst_structure_copy                  (const GstStructure *structure);

Duplicates a GstStructure and all its fields and values.

gst_structure_free ()

void                gst_structure_free                  (GstStructure *structure);

Frees a GstStructure and all its fields and values. The structure must not have a parent when this function is called.

gst_structure_get_name ()

const gchar*        gst_structure_get_name              (const GstStructure *structure);

Get the name of structure as a string.

gst_structure_has_name ()

gboolean            gst_structure_has_name              (const GstStructure *structure,
                                                         const gchar *name);

Checks if the structure has the given name

gst_structure_set_name ()

void                gst_structure_set_name              (GstStructure *structure,
                                                         const gchar *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 "/-_.:".

gst_structure_get_name_id ()

GQuark              gst_structure_get_name_id           (const GstStructure *structure);

Get the name of structure as a GQuark.

gst_structure_id_get ()

gboolean            gst_structure_id_get                (GstStructure *structure,
                                                         GQuark first_field_id,
                                                         ...);

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 gst_structure_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.

Since 0.10.24

gst_structure_id_get_valist ()

gboolean            gst_structure_id_get_valist         (GstStructure *structure,
                                                         GQuark first_field_id,
                                                         va_list 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.

Since 0.10.24

gst_structure_id_get_value ()

const GValue*       gst_structure_id_get_value          (const GstStructure *structure,
                                                         GQuark field);

Get the value of the field with GQuark field.

gst_structure_id_set_value ()

void                gst_structure_id_set_value          (GstStructure *structure,
                                                         GQuark field,
                                                         const GValue *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.

gst_structure_get ()

gboolean            gst_structure_get                   (GstStructure *structure,
                                                         const char *first_fieldname,
                                                         ...);

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.

Since 0.10.24

gst_structure_get_valist ()

gboolean            gst_structure_get_valist            (GstStructure *structure,
                                                         const char *first_fieldname,
                                                         va_list 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.

Since 0.10.24

gst_structure_get_value ()

const GValue*       gst_structure_get_value             (const GstStructure *structure,
                                                         const gchar *fieldname);

Get the value of the field with name fieldname.

gst_structure_set_value ()

void                gst_structure_set_value             (GstStructure *structure,
                                                         const gchar *fieldname,
                                                         const GValue *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.

gst_structure_set ()

void                gst_structure_set                   (GstStructure *structure,
                                                         const gchar *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.

gst_structure_set_valist ()

void                gst_structure_set_valist            (GstStructure *structure,
                                                         const gchar *fieldname,
                                                         va_list varargs);

va_list form of gst_structure_set().

gst_structure_id_set ()

void                gst_structure_id_set                (GstStructure *structure,
                                                         GQuark 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.

Since 0.10.10

gst_structure_id_set_valist ()

void                gst_structure_id_set_valist         (GstStructure *structure,
                                                         GQuark fieldname,
                                                         va_list varargs);

va_list form of gst_structure_id_set().

Since 0.10.10

gst_structure_remove_field ()

void                gst_structure_remove_field          (GstStructure *structure,
                                                         const gchar *fieldname);

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

gst_structure_remove_fields ()

void                gst_structure_remove_fields         (GstStructure *structure,
                                                         const gchar *fieldname,
                                                         ...);

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

gst_structure_remove_fields_valist ()

void                gst_structure_remove_fields_valist  (GstStructure *structure,
                                                         const gchar *fieldname,
                                                         va_list varargs);

va_list form of gst_structure_remove_fields().

gst_structure_remove_all_fields ()

void                gst_structure_remove_all_fields     (GstStructure *structure);

Removes all fields in a GstStructure.

gst_structure_get_field_type ()

GType               gst_structure_get_field_type        (const GstStructure *structure,
                                                         const gchar *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.

gst_structure_foreach ()

gboolean            gst_structure_foreach               (const GstStructure *structure,
                                                         GstStructureForeachFunc func,
                                                         gpointer user_data);

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().

gst_structure_n_fields ()

gint                gst_structure_n_fields              (const GstStructure *structure);

Get the number of fields in the structure.

gst_structure_has_field ()

gboolean            gst_structure_has_field             (const GstStructure *structure,
                                                         const gchar *fieldname);

Check if structure contains a field named fieldname.

gst_structure_has_field_typed ()

gboolean            gst_structure_has_field_typed       (const GstStructure *structure,
                                                         const gchar *fieldname,
                                                         GType type);

Check if structure contains a field named fieldname and with GType type.

gst_structure_get_boolean ()

gboolean            gst_structure_get_boolean           (const GstStructure *structure,
                                                         const gchar *fieldname,
                                                         gboolean *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.

gst_structure_get_int ()

gboolean            gst_structure_get_int               (const GstStructure *structure,
                                                         const gchar *fieldname,
                                                         gint *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.

gst_structure_get_uint ()

gboolean            gst_structure_get_uint              (const GstStructure *structure,
                                                         const gchar *fieldname,
                                                         guint *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.

Since 0.10.15

gst_structure_get_fourcc ()

gboolean            gst_structure_get_fourcc            (const GstStructure *structure,
                                                         const gchar *fieldname,
                                                         guint32 *value);

Sets the GstFourcc 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.

gst_structure_get_double ()

gboolean            gst_structure_get_double            (const GstStructure *structure,
                                                         const gchar *fieldname,
                                                         gdouble *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.

gst_structure_get_string ()

const gchar*        gst_structure_get_string            (const GstStructure *structure,
                                                         const gchar *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.

gst_structure_get_date ()

gboolean            gst_structure_get_date              (const GstStructure *structure,
                                                         const gchar *fieldname,
                                                         GDate **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).

gst_structure_get_clock_time ()

gboolean            gst_structure_get_clock_time        (const GstStructure *structure,
                                                         const gchar *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.

gst_structure_get_enum ()

gboolean            gst_structure_get_enum              (const GstStructure *structure,
                                                         const gchar *fieldname,
                                                         GType enumtype,
                                                         gint *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.

gst_structure_get_fraction ()

gboolean            gst_structure_get_fraction          (const GstStructure *structure,
                                                         const gchar *fieldname,
                                                         gint *value_numerator,
                                                         gint *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.

gst_structure_map_in_place ()

gboolean            gst_structure_map_in_place          (GstStructure *structure,
                                                         GstStructureMapFunc func,
                                                         gpointer user_data);

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.

gst_structure_nth_field_name ()

const gchar*        gst_structure_nth_field_name        (const GstStructure *structure,
                                                         guint index);

Get the name of the given field number, counting from 0 onwards.

gst_structure_set_parent_refcount ()

void                gst_structure_set_parent_refcount   (GstStructure *structure,
                                                         gint *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.

gst_structure_to_string ()

gchar*              gst_structure_to_string             (const GstStructure *structure);

Converts structure to a human-readable string representation.

For debugging purposes its easier to do something like this:

GST_LOG ("structure is %" GST_PTR_FORMAT, structure);

This prints the structure in human readble form.

gst_structure_from_string ()

GstStructure*       gst_structure_from_string           (const gchar *string,
                                                         gchar **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.

gst_structure_fixate_field_nearest_int ()

gboolean            gst_structure_fixate_field_nearest_int
                                                        (GstStructure *structure,
                                                         const char *field_name,
                                                         int target);

Fixates a GstStructure by changing the given field to the nearest integer to target that is a subset of the existing field.

gst_structure_fixate_field_nearest_double ()

gboolean            gst_structure_fixate_field_nearest_double
                                                        (GstStructure *structure,
                                                         const char *field_name,
                                                         double target);

Fixates a GstStructure by changing the given field to the nearest double to target that is a subset of the existing field.

gst_structure_fixate_field_nearest_fraction ()

gboolean            gst_structure_fixate_field_nearest_fraction
                                                        (GstStructure *structure,
                                                         const char *field_name,
                                                         const gint target_numerator,
                                                         const gint target_denominator);

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.

gst_structure_fixate_field_boolean ()

gboolean            gst_structure_fixate_field_boolean  (GstStructure *structure,
                                                         const char *field_name,
                                                         gboolean target);

Fixates a GstStructure by changing the given field_name field to the given target boolean if that field is not fixed yet.