## GstStructure

GstStructure — Generic structure containing fields of names and values

## Synopsis

    #define     GST_TYPE_STRUCTURE
    struct      GstStructure;
    gboolean    (*GstStructureForeachFunc)      (GQuark field_id,
                                                 GValue *value,
                                                 gpointer user_data);
    GstStructure* gst_structure_empty_new       (const gchar *name);
    GstStructure* gst_structure_id_empty_new    (GQuark quark);
    GstStructure* gst_structure_new             (const gchar *name,
                                                 const gchar *firstfield,
                                                 ...);
    GstStructure* gst_structure_new_valist      (const gchar *name,
                                                 const gchar *firstfield,
                                                 va_list varargs);
    GstStructure* gst_structure_copy            (const GstStructure *structure);
    void        gst_structure_free              (GstStructure *structure);
    G_CONST_RETURN gchar* gst_structure_get_name
                                                (const GstStructure *structure);
    void        gst_structure_set_name          (GstStructure *structure,
                                                 const gchar *name);
    GQuark      gst_structure_get_name_id       (const GstStructure *structure);
    G_CONST_RETURN GValue* gst_structure_id_get_value
                                                (const GstStructure *structure,
                                                 GQuark field);
    void        gst_structure_id_set_value      (GstStructure *structure,
                                                 GQuark field,
                                                 const GValue *value);
    G_CONST_RETURN GValue* gst_structure_get_value
                                                (const GstStructure *structure,
                                                 const gchar *fieldname);
    void        gst_structure_set_value         (GstStructure *structure,
                                                 const gchar *fieldname,
                                                 const GValue *value);
    void        gst_structure_set               (GstStructure *structure,
                                                 const gchar *fieldname,
                                                 ...);
    void        gst_structure_set_valist        (GstStructure *structure,
                                                 const gchar *fieldname,
                                                 va_list varargs);
    void        gst_structure_remove_field      (GstStructure *structure,
                                                 const gchar *fieldname);
    void        gst_structure_remove_fields     (GstStructure *structure,
                                                 const gchar *fieldname,
                                                 ...);
    void        gst_structure_remove_fields_valist
                                                (GstStructure *structure,
                                                 const gchar *fieldname,
                                                 va_list varargs);
    void        gst_structure_remove_all_fields (GstStructure *structure);
    GType       gst_structure_get_field_type    (const GstStructure *structure,
                                                 const gchar *fieldname);
    gboolean    gst_structure_foreach           (GstStructure *structure,
                                                 GstStructureForeachFunc func,
                                                 gpointer user_data);
    gint        gst_structure_n_fields          (const GstStructure *structure);
    gboolean    gst_structure_has_field         (const GstStructure *structure,
                                                 const gchar *fieldname);
    gboolean    gst_structure_has_field_typed   (const GstStructure *structure,
                                                 const gchar *fieldname,
                                                 GType type);
    gboolean    gst_structure_get_boolean       (const GstStructure *structure,
                                                 const gchar *fieldname,
                                                 gboolean *value);
    gboolean    gst_structure_get_int           (const GstStructure *structure,
                                                 const gchar *fieldname,
                                                 gint *value);
    gboolean    gst_structure_get_fourcc        (const GstStructure *structure,
                                                 const gchar *fieldname,
                                                 guint32 *value);
    gboolean    gst_structure_get_double        (const GstStructure *structure,
                                                 const gchar *fieldname,
                                                 gdouble *value);
    G_CONST_RETURN gchar* gst_structure_get_string
                                                (const GstStructure *structure,
                                                 const gchar *fieldname);
    gchar*      gst_structure_to_string         (const GstStructure *structure);
    GstStructure* gst_structure_from_string     (const gchar *string,
                                                 gchar **end);

## Description

## Details

### GST_TYPE_STRUCTURE

    #define GST_TYPE_STRUCTURE             (gst_structure_get_type ())

### struct GstStructure

    struct GstStructure {

      GType type;

      GQuark name;

      GArray *fields;

      gpointer _gst_reserved[GST_PADDING];
    };

### GstStructureForeachFunc ()

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

`field_id` : |
`value` : |
`user_data` : |
Returns : |

### gst_structure_empty_new ()

    GstStructure* gst_structure_empty_new       (const gchar *name);

Creates a new, empty GstStructure with the given name.

`name` : | name of new structure
Returns : | a new, empty GstStructure

### gst_structure_id_empty_new ()

    GstStructure* gst_structure_id_empty_new    (GQuark quark);

Creates a new, empty GstStructure with the given name.

`quark` : | name of new structure
Returns : | a new, empty GstStructure

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

`name` : | name of new structure
`firstfield` : | name of first field to set
`...` : | additional arguments
Returns : | a new GstStructure

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

`name` : | name of new structure
`firstfield` : | name of first field to set
`varargs` : | variable argument list
Returns : | a new GstStructure

### gst_structure_copy ()

    GstStructure* gst_structure_copy            (const GstStructure *structure);

Duplicates a GstStructure and all its fields and values.

`structure` : | a GstStructure to duplicate
Returns : | a new GstStructure.

### gst_structure_free ()

    void        gst_structure_free              (GstStructure *structure);

Frees a GstStructure and all its fields and values.

`structure` : | the GstStructure to free

### gst_structure_get_name ()

    G_CONST_RETURN gchar* gst_structure_get_name
                                                (const GstStructure *structure);

Accessor fuction.

`structure` : | a GstStructure
Returns : | the quark representing 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.

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

### gst_structure_get_name_id ()

    GQuark      gst_structure_get_name_id       (const GstStructure *structure);

`structure` : |
Returns : |

### gst_structure_id_get_value ()

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

Accessor function.

`structure` : | a GstStructure
`field` : | the GQuark of the field to get
Returns : | the GValue corresponding to the field with the given name identifier.

### gst_structure_id_set_value ()

    void        gst_structure_id_set_value      (GstStructure *structure,
                                                 GQuark field,
                                                 const GValue *value);

Sets the field with the given ID to the provided value. If the field does not exist, it is created. If the field exists, the previous value is freed.

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

### gst_structure_get_value ()

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

Accessor function.

`structure` : | a GstStructure
`fieldname` : | the name of the field to get
Returns : | the GValue corresponding to the field with the given name.

### gst_structure_set_value ()

    void        gst_structure_set_value         (GstStructure *structure,
                                                 const gchar *fieldname,
                                                 const GValue *value);

Sets the field with the given name to the provided value. If the field does not exist, it is created. If the field exists, the previous value is freed.

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

### 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. The last variable argument should be NULL.

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

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

`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 field with the given names. If a field does not exist, the argument is ignored.

`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);

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

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

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

`structure` : | a GstStructure
`fieldname` : | the name of the field
Returns : | the GValue of the field

### gst_structure_foreach ()

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

Calls the provided function once for each field in the GstStructure.

`structure` : | a GstStructure
`func` : | a function to call for each field
`user_data` : | private data
Returns : | TRUE if the supplied function returns TRUE For each of the fields, FALSE otherwise.

### gst_structure_n_fields ()

    gint        gst_structure_n_fields          (const GstStructure *structure);

Accessor function.

`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);

Accessor function.

`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);

Accessor function.

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

`structure` : | a GstStructure
`fieldname` : | the name of a field
`value` : | a pointer to a gboolean to set
Returns : | TRUE if the value could be set correctly

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

`structure` : | a GstStructure
`fieldname` : | the name of a field
`value` : | a pointer to an int to set
Returns : | TRUE if the value could be set correctly

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

`structure` : | a GstStructure
`fieldname` : | the name of a field
`value` : | a pointer to a GstFourcc to set
Returns : | TRUE if the value could be set correctly

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

`structure` : | a GstStructure
`fieldname` : | the name of a field
`value` : | a pointer to a GstFourcc to set
Returns : | TRUE if the value could be set correctly

### gst_structure_get_string ()

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

`structure` : | a GstStructure
`fieldname` : | the name of a field
Returns : | a pointer to the string

### gst_structure_to_string ()

    gchar*      gst_structure_to_string         (const GstStructure *structure);

Converts `structure` to a human-readable representation.

`structure` : | a GstStructure
Returns : | a pointer to string allocated by `g_malloc()`

### gst_structure_from_string ()

    GstStructure* gst_structure_from_string     (const gchar *string,
                                                 gchar **end);

Creates a GstStructure from a string representation.

`string` : | a string representation of a GstStructure.
`end` : | FIXME, deduce from code
Returns : | a new GstStructure