GstStructure

GstStructure — Generic structure containing fields of names and values

Functions

gboolean (*GstStructureForeachFunc) ()
gboolean (*GstStructureMapFunc) ()
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_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 ()
gboolean gst_structure_foreach ()
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_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_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

Object Hierarchy


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

Last reviewed on 2012-03-29 (0.11.3)

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.


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.

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]

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.


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.


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

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

Interesects struct1 and struct2 and returns the intersection.

Parameters

struct1

a GstStructure

 

struct2

a GstStructure

 

Returns

Intersection of struct1 and struct2


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


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_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_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 readble form.

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]


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