GstStructure: GStreamer Core Reference Manual

## GstStructure GstStructure — Generic structure containing fields of names and values |

## Functions

gboolean | (*GstStructureForeachFunc) ()
gboolean | (*GstStructureMapFunc) ()
gboolean | (*GstStructureFilterMapFunc) ()
GstStructure * | gst_structure_new_empty ()
GstStructure * | gst_structure_new_id_empty ()
GstStructure * | gst_structure_new ()
GstStructure * | gst_structure_new_valist ()
GstStructure * | gst_structure_new_id ()
GstStructure * | gst_structure_new_from_string ()
GstStructure * | gst_structure_copy ()
void | gst_structure_free ()
const gchar * | gst_structure_get_name ()
gboolean | gst_structure_has_name ()
void | gst_structure_set_name ()
GQuark | gst_structure_get_name_id ()
gboolean | gst_structure_id_get ()
gboolean | gst_structure_id_get_valist ()
const GValue * | gst_structure_id_get_value ()
void | gst_structure_id_set_value ()
void | gst_structure_id_take_value ()
gboolean | gst_structure_get ()
gboolean | gst_structure_get_valist ()
const GValue * | gst_structure_get_value ()
void | gst_structure_set_value ()
void | gst_structure_set_array ()
void | gst_structure_set_list ()
void | gst_structure_take_value ()
void | gst_structure_set ()
void | gst_structure_set_valist ()
void | gst_structure_id_set ()
void | gst_structure_id_set_valist ()
void | gst_structure_remove_field ()
void | gst_structure_remove_fields ()
void | gst_structure_remove_fields_valist ()
void | gst_structure_remove_all_fields ()
GType | gst_structure_get_field_type ()
gint | gst_structure_n_fields ()
gboolean | gst_structure_has_field ()
gboolean | gst_structure_has_field_typed ()
gboolean | gst_structure_is_equal ()
gboolean | gst_structure_is_subset ()
gboolean | gst_structure_can_intersect ()
GstStructure * | gst_structure_intersect ()
gboolean | gst_structure_id_has_field ()
gboolean | gst_structure_id_has_field_typed ()
gboolean | gst_structure_get_boolean ()
gboolean | gst_structure_get_int ()
gboolean | gst_structure_get_uint ()
gboolean | gst_structure_get_int64 ()
gboolean | gst_structure_get_uint64 ()
gboolean | gst_structure_get_double ()
const gchar * | gst_structure_get_string ()
gboolean | gst_structure_get_date ()
gboolean | gst_structure_get_date_time ()
gboolean | gst_structure_get_clock_time ()
gboolean | gst_structure_get_enum ()
gboolean | gst_structure_get_fraction ()
gboolean | gst_structure_get_array ()
gboolean | gst_structure_get_list ()
gboolean | gst_structure_foreach ()
gboolean | gst_structure_map_in_place ()
void | gst_structure_filter_and_map_in_place ()
const gchar * | gst_structure_nth_field_name ()
gboolean | gst_structure_set_parent_refcount ()
gchar * | gst_structure_to_string ()
GstStructure * | gst_structure_from_string ()
void | gst_structure_fixate ()
gboolean | gst_structure_fixate_field ()
gboolean | gst_structure_fixate_field_nearest_int ()
gboolean | gst_structure_fixate_field_nearest_double ()
gboolean | gst_structure_fixate_field_nearest_fraction ()
gboolean | gst_structure_fixate_field_boolean ()
gboolean | gst_structure_fixate_field_string ()

## Types and Values

struct | GstStructure

## Includes

    #include <gst/gst.h>

## Description

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.

Be aware that the current GstCaps / GstStructure serialization into string has limited support for nested GstCaps / GstStructure fields. It can only support one level of nesting. Using more levels will lead to unexpected behavior when using serialization features, such as `gst_caps_to_string()` or `gst_value_serialize()` and their counterparts.

## Functions

### 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` .

#### Parameters

field_id | the GQuark of the field name |
value | the GValue of the field |
user_data | user data |

#### Returns

`TRUE` if the foreach operation should continue, `FALSE` if the foreach operation should stop with `FALSE`.

### 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` .

#### Parameters

field_id | the GQuark of the field name |
value | the GValue of the field |
user_data | user data |

#### Returns

`TRUE` if the map operation should continue, `FALSE` if the map operation should stop with `FALSE`.

### GstStructureFilterMapFunc ()

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

A function that will be called in `gst_structure_filter_and_map_in_place()`. The function may modify `value` , and the value will be removed from the structure if `FALSE` is returned.

#### Parameters

field_id | the GQuark of the field name |
value | the GValue of the field |
user_data | user data |

#### Returns

`TRUE` if the field should be preserved, `FALSE` if it should be removed.

### gst_structure_new_empty ()

    GstStructure *
    gst_structure_new_empty (const gchar *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

#### Parameters

name | name of new structure |

#### Returns

a new, empty GstStructure.

[transfer full]

### gst_structure_new_id_empty ()

    GstStructure *
    gst_structure_new_id_empty (GQuark quark);

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

Free-function: gst_structure_free

#### Parameters

quark | name of new structure |

#### Returns

a new, empty GstStructure.

[transfer full]

### 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`.

Free-function: gst_structure_free

#### Parameters

name | name of new structure |
firstfield | name of first field to set |
... | additional arguments |

#### Returns

a new GstStructure.

[transfer full]

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

Free-function: gst_structure_free

#### Parameters

name | name of new structure |
firstfield | name of first field to set |
varargs | variable argument list |

#### Returns

a new GstStructure.

[transfer full]

### gst_structure_new_id ()

    GstStructure *
    gst_structure_new_id (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_new_id_empty()` and `gst_structure_id_set()`.

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

Free-function: gst_structure_free

#### Parameters

name_quark | name of new structure |
field_quark | the GQuark for the name of the field to set |
... | variable arguments |

#### Returns

a new GstStructure.

[transfer full]

### gst_structure_new_from_string ()

    GstStructure *
    gst_structure_new_from_string (const gchar *string);

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.

The current implementation of serialization will lead to unexpected results when there are nested GstCaps / GstStructure deeper than one level.

Free-function: gst_structure_free

#### Parameters

string | a string representation of a GstStructure |

#### Returns

a new GstStructure or `NULL` when the string could not be parsed. Free with `gst_structure_free()` after use.

[transfer full][nullable]

Since: 1.2

### gst_structure_copy ()

    GstStructure *
    gst_structure_copy (const GstStructure *structure);

Duplicates a GstStructure and all its fields and values.

Free-function: gst_structure_free

#### Parameters

structure | a GstStructure to duplicate |

#### Returns

a new GstStructure.

[transfer full]

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

#### Parameters

structure | the GstStructure to free. | [in][transfer full]

### gst_structure_get_name ()

    const gchar *
    gst_structure_get_name (const GstStructure *structure);

Get the name of `structure` as a string.

#### Parameters

structure | a GstStructure |

#### Returns

the name of the structure.

### gst_structure_has_name ()

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

Checks if the structure has the given name

#### Parameters

structure | a GstStructure |
name | structure name to check for |

#### Returns

`TRUE` if `name` matches the name of the structure.

### 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 "/-_.:".

#### Parameters

structure | a GstStructure |
name | the new name of the structure |

### gst_structure_get_name_id ()

    GQuark
    gst_structure_get_name_id (const GstStructure *structure);

Get the name of `structure` as a GQuark.

#### Parameters

structure | a GstStructure |

#### Returns

the quark representing the name of the structure.

### gst_structure_id_get ()

    gboolean
    gst_structure_id_get (const 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 receive a new reference which you must release with a suitable `_unref()` when no longer needed. For strings and boxed types you will receive a copy which you will need to release with either `g_free()` or the suitable function for the boxed type.

#### Parameters

structure | a GstStructure |
first_field_id | the quark of the first field to read |
... | variable arguments |

#### Returns

`FALSE` if there was a problem reading any of the fields (e.g. because the field requested did not exist, or was of a type other than the type specified), otherwise `TRUE`.

### gst_structure_id_get_valist ()

    gboolean
    gst_structure_id_get_valist (const 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.

#### Parameters

structure | a GstStructure |
first_field_id | the quark of the first field to read |
args | variable arguments |

#### Returns

`TRUE`, or `FALSE` if there was a problem reading any of the fields

### 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` .

#### Parameters

structure | a GstStructure |
field | the GQuark of the field to get |

#### Returns

the GValue corresponding to the field with the given name identifier.

[nullable]

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

#### Parameters

structure | a GstStructure |
field | a GQuark representing a field |
value | the new value of the field |

### gst_structure_id_take_value ()

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

#### Parameters

structure | a GstStructure |
field | a GQuark representing a field |
value | the new value of the field. | [transfer full]

### gst_structure_get ()

    gboolean
    gst_structure_get (const 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 receive a new reference which you must release with a suitable `_unref()` when no longer needed. For strings and boxed types you will receive a copy which you will need to release with either `g_free()` or the suitable function for the boxed type.

#### Parameters

structure | a GstStructure |
first_fieldname | the name of the first field to read |
... | variable arguments |

#### Returns

`FALSE` if there was a problem reading any of the fields (e.g. because the field requested did not exist, or was of a type other than the type specified), otherwise `TRUE`.

### gst_structure_get_valist ()

    gboolean
    gst_structure_get_valist (const 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.

#### Parameters

structure | a GstStructure |
first_fieldname | the name of the first field to read |
args | variable arguments |

#### Returns

`TRUE`, or `FALSE` if there was a problem reading any of the fields

### 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` .

#### Parameters

structure | a GstStructure |
fieldname | the name of the field to get |

#### Returns

the GValue corresponding to the field with the given name.

[nullable]

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

#### Parameters

structure | a GstStructure |
fieldname | the name of the field to set |
value | the new value of the field |

### gst_structure_set_array ()

    void
    gst_structure_set_array (GstStructure *structure,
                             const gchar *fieldname,
                             const GValueArray *array);

This is useful in language bindings where unknown GValue types are not supported. This function will convert a `array` to `GST_TYPE_ARRAY` and set the field specified by `fieldname` . Be aware that this is slower then using `GST_TYPE_ARRAY` in a GValue directly.

Since 1.12

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
array | a pointer to a GValueArray |

### gst_structure_set_list ()

    void
    gst_structure_set_list (GstStructure *structure,
                            const gchar *fieldname,
                            const GValueArray *array);

This is useful in language bindings where unknown GValue types are not supported. This function will convert a `array` to `GST_TYPE_LIST` and set the field specified by `fieldname` . Be aware that this is slower then using `GST_TYPE_LIST` in a GValue directly.

Since 1.12

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
array | a pointer to a GValueArray |

### gst_structure_take_value ()

    void
    gst_structure_take_value (GstStructure *structure,
                              const gchar *fieldname,
                              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. The function will take ownership of `value` .

#### Parameters

structure | a GstStructure |
fieldname | the name of the field to set |
value | the new value of the field. | [transfer full]

### gst_structure_set ()

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

Parses the variable arguments and sets fields accordingly. Fields that weren't already part of the structure are added as needed. Variable arguments should be in the form field name, field type (as a GType), value(s). The last variable argument should be `NULL`.

#### Parameters

structure | a GstStructure |
fieldname | the name of the field to set |
... | variable arguments |

### gst_structure_set_valist ()

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

va_list form of `gst_structure_set()`.

#### Parameters

structure | a GstStructure |
fieldname | the name of the field to set |
varargs | variable arguments |

### 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`.

#### Parameters

structure | a GstStructure |
fieldname | the GQuark for the name of the field to set |
... | variable arguments |

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

#### Parameters

structure | a GstStructure |
fieldname | the name of the field to set |
varargs | variable arguments |

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

#### Parameters

structure | a GstStructure |
fieldname | the name of the field to remove |

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

#### Parameters

structure | a GstStructure |
fieldname | the name of the field to remove |
... | `NULL`-terminated list of more fieldnames to remove |

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

#### Parameters

structure | a GstStructure |
fieldname | the name of the field to remove |
varargs | `NULL`-terminated list of more fieldnames to remove |

### gst_structure_remove_all_fields ()

    void
    gst_structure_remove_all_fields (GstStructure *structure);

Removes all fields in a GstStructure.

#### Parameters

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

#### Parameters

structure | a GstStructure |
fieldname | the name of the field |

#### Returns

the GValue of the field

### gst_structure_n_fields ()

    gint
    gst_structure_n_fields (const GstStructure *structure);

Get the number of fields in the structure.

#### Parameters

structure | a GstStructure |

#### Returns

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

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |

#### Returns

`TRUE` if the structure contains a field with the given name

### 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` .

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
type | the type of a value |

#### Returns

`TRUE` if the structure contains a field with the given name and type

### gst_structure_is_equal ()

    gboolean
    gst_structure_is_equal (const GstStructure *structure1,
                            const GstStructure *structure2);

Tests if the two GstStructure are equal.

#### Parameters

structure1 | a GstStructure. |
structure2 | a GstStructure. |

#### Returns

`TRUE` if the two structures have the same name and field.

### gst_structure_is_subset ()

    gboolean
    gst_structure_is_subset (const GstStructure *subset,
                             const GstStructure *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` .

#### Parameters

subset | a GstStructure |
superset | a potentially greater GstStructure |

#### Returns

`TRUE` if `subset` is a subset of `superset`

### gst_structure_can_intersect ()

    gboolean
    gst_structure_can_intersect (const GstStructure *struct1,
                                 const GstStructure *struct2);

Tries intersecting `struct1` and `struct2` and reports whether the result would not be empty.

#### Parameters

struct1 | a GstStructure |
struct2 | a GstStructure |

#### Returns

`TRUE` if intersection would not be empty

### gst_structure_intersect ()

    GstStructure *
    gst_structure_intersect (const GstStructure *struct1,
                             const GstStructure *struct2);

Intersects `struct1` and `struct2` and returns the intersection.

#### Parameters

struct1 | a GstStructure |
struct2 | a GstStructure |

#### Returns

Intersection of `struct1` and `struct2` .

[nullable]

### gst_structure_id_has_field ()

    gboolean
    gst_structure_id_has_field (const GstStructure *structure,
                                GQuark field);

Check if `structure` contains a field named `field` .

#### Parameters

structure | a GstStructure |
field | GQuark of the field name |

#### Returns

`TRUE` if the structure contains a field with the given name

### gst_structure_id_has_field_typed ()

    gboolean
    gst_structure_id_has_field_typed (const GstStructure *structure,
                                      GQuark field,
                                      GType type);

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

#### Parameters

structure | a GstStructure |
field | GQuark of the field name |
type | the type of a value |

#### Returns

`TRUE` if the structure contains a field with the given name and 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.

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
value | a pointer to a gboolean to set. | [out]

#### Returns

`TRUE` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a boolean, this function returns `FALSE`.

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

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
value | a pointer to an int to set. | [out]

#### Returns

`TRUE` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain an int, this function returns `FALSE`.

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

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
value | a pointer to a uint to set. | [out]

#### Returns

`TRUE` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a uint, this function returns `FALSE`.

### gst_structure_get_int64 ()

    gboolean
    gst_structure_get_int64 (const GstStructure *structure,
                             const gchar *fieldname,
                             gint64 *value);

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

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
value | a pointer to a gint64 to set. | [out]

#### Returns

`TRUE` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a gint64, this function returns `FALSE`.

Since: 1.4

### gst_structure_get_uint64 ()

    gboolean
    gst_structure_get_uint64 (const GstStructure *structure,
                              const gchar *fieldname,
                              guint64 *value);

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

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
value | a pointer to a guint64 to set. | [out]

#### Returns

`TRUE` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a guint64, this function returns `FALSE`.

Since: 1.4

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

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
value | a pointer to a gdouble to set. | [out]

#### Returns

`TRUE` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a double, this function returns `FALSE`.

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

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |

#### Returns

a pointer to the string or `NULL` when the field did not exist or did not contain a string.

[nullable]

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

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
value | a pointer to a GDate to set. | [out callee-allocates]

#### Returns

`TRUE` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a data, this function returns `FALSE`.

### gst_structure_get_date_time ()

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

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
value | a pointer to a GstDateTime to set. | [out callee-allocates]

#### Returns

`TRUE` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a data, this function returns `FALSE`.

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

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
value | a pointer to a GstClockTime to set. | [out]

#### Returns

`TRUE` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a GstClockTime, this function returns `FALSE`.

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

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
enumtype | the enum type of a field |
value | a pointer to an int to set. | [out]

#### Returns

`TRUE` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain an enum of the given type, this function returns `FALSE`.

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

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
value_numerator | a pointer to an int to set. | [out]
value_denominator | a pointer to an int to set. | [out]

#### Returns

`TRUE` if the values could be set correctly. If there was no field with `fieldname` or the existing field did not contain a GstFraction, this function returns `FALSE`.

### gst_structure_get_array ()

    gboolean
    gst_structure_get_array (GstStructure *structure,
                             const gchar *fieldname,
                             GValueArray **array);

This is useful in language bindings where unknown GValue types are not supported. This function will convert the `GST_TYPE_ARRAY` into a newly allocated GValueArray and return it through `array` . Be aware that this is slower then getting the GValue directly.

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
array | a pointer to a GValueArray. | [out]

#### Returns

`TRUE` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a `GST_TYPE_ARRAY`, this function returns `FALSE`.

### gst_structure_get_list ()

    gboolean
    gst_structure_get_list (GstStructure *structure,
                            const gchar *fieldname,
                            GValueArray **array);

This is useful in language bindings where unknown GValue types are not supported. This function will convert the `GST_TYPE_LIST` into a newly allocated GValueArray and return it through `array` . Be aware that this is slower then getting the GValue directly.

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
array | a pointer to a GValueArray. | [out]

#### Returns

`TRUE` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a `GST_TYPE_LIST`, this function returns `FALSE`.

Since 1.12

### 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()` and `gst_structure_filter_and_map_in_place()`.

#### Parameters

structure | a GstStructure |
func | a function to call for each field. | [scope call]
user_data | private data. | [closure]

#### Returns

`TRUE` if the supplied function returns `TRUE` For each of the fields, `FALSE` otherwise.

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

#### Parameters

structure | a GstStructure |
func | a function to call for each field. | [scope call]
user_data | private data. | [closure]

#### Returns

`TRUE` if the supplied function returns `TRUE` For each of the fields, `FALSE` otherwise.

### gst_structure_filter_and_map_in_place ()

    void
    gst_structure_filter_and_map_in_place (GstStructure *structure,
                                           GstStructureFilterMapFunc 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 the fields. In contrast to `gst_structure_map_in_place()`, the field is removed from the structure if `FALSE` is returned from the function. The structure must be mutable.

#### Parameters

structure | a GstStructure |
func | a function to call for each field. | [scope call]
user_data | private data. | [closure]

Since: 1.6

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

#### Parameters

structure | a GstStructure |
index | the index to get the name of |

#### Returns

the name of the given field number

### gst_structure_set_parent_refcount ()

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

#### Parameters

structure | a GstStructure |
refcount | a pointer to the parent's refcount. | [in]

#### Returns

`TRUE` if the parent refcount could be set.

### 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:

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

This prints the structure in human readable form.

The current implementation of serialization will lead to unexpected results when there are nested GstCaps / GstStructure deeper than one level.

Free-function: g_free

#### Parameters

structure | a GstStructure |

#### Returns

a pointer to string allocated by `g_malloc()`. `g_free()` after usage.

[transfer full]

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

Free-function: gst_structure_free

#### Parameters

string | a string representation of a GstStructure. |
end | pointer to store the end of the string in. | [out][allow-none][transfer none][skip]

#### Returns

a new GstStructure or `NULL` when the string could not be parsed. Free with `gst_structure_free()` after use.

[transfer full][nullable]

### gst_structure_fixate ()

    void
    gst_structure_fixate (GstStructure *structure);

Fixate all values in `structure` using `gst_value_fixate()`. `structure` will be modified in-place and should be writable.

#### Parameters

structure | a GstStructure |

### gst_structure_fixate_field ()

    gboolean
    gst_structure_fixate_field (GstStructure *structure,
                                const char *field_name);

Fixates a GstStructure by changing the given field with its fixated value.

#### Parameters

structure | a GstStructure |
field_name | a field in `structure` |

#### Returns

`TRUE` if the structure field could be fixated

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

#### Parameters

structure | a GstStructure |
field_name | a field in `structure` |
target | the target value of the fixation |

#### Returns

`TRUE` if the structure could be fixated

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

#### Parameters

structure | a GstStructure |
field_name | a field in `structure` |
target | the target value of the fixation |

#### Returns

`TRUE` if the structure could be fixated

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

#### Parameters

structure | a GstStructure |
field_name | a field in `structure` |
target_numerator | The numerator of the target value of the fixation |
target_denominator | The denominator of the target value of the fixation |

#### Returns

`TRUE` if the structure could be fixated

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

#### Parameters

structure | a GstStructure |
field_name | a field in `structure` |
target | the target value of the fixation |

#### Returns

`TRUE` if the structure could be fixated

### gst_structure_fixate_field_string ()

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

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

#### Parameters

structure | a GstStructure |
field_name | a field in `structure` |
target | the target value of the fixation |

#### Returns

`TRUE` if the structure could be fixated

## Types and Values

### struct GstStructure

    struct GstStructure {
      GType type;
    };

The GstStructure object. Most fields are private.

#### Members

GType `type`; | the GType of a structure |

## See Also

GstCaps, GstMessage, GstEvent, GstQuery