GstStructure - Guile-GStreamer

A <gst-structure> is a collection of key/value pairs. The keys are expressed as GQuarks and the values can be of any GType.

In addition to the key/value pairs, a <gst-structure> also has a name. The name starts with a letter and can be folled by letters, numbers and any of "/-_.:".

<gst-structure> is used by various GStreamer subsystems to store information in a flexible and extensible way. A <gst-structure> does not have a refcount because it usually is part of a higher level object such as <gst-caps>. It provides a means to enforce mutability using the refcount of the parent with the gst-structure-set-parent-refcount method.

A <gst-structure> can be created with gst-structure-empty-new 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.

33.2 Usage

— Class: <gst-structure>

— Function: gst-structure-empty-new (name mchars) (ret <gst-structure>)

Creates a new, empty <gst-structure> with the given name.
See gst-structure-set-name for constraints on the name parameter.

name
name of new structure
ret
a new, empty <gst-structure>

— Function: gst-structure-id-empty-new (quark unsigned-int) (ret <gst-structure>)

Creates a new, empty <gst-structure> with the given name as a GQuark.

quark
name of new structure
ret
a new, empty <gst-structure>

— Function: gst-structure-get-name (self <gst-structure>) (ret mchars)

Get the name of structure as a string.

structure
a <gst-structure>
ret
the name of the structure.

— Function: gst-structure-has-name (self <gst-structure>) (name mchars) (ret bool)

Checks if the structure has the given name

structure
a <gst-structure>
name
structure name to check for
ret
TRUE if name matches the name of the structure.

— Function: gst-structure-set-name (self <gst-structure>) (name mchars)

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

structure
a <gst-structure>
name
the new name of the structure

— Function: gst-structure-get-name-id (self <gst-structure>) (ret unsigned-int)

Get the name of structure as a GQuark.

structure
a <gst-structure>
ret
the quark representing the name of the structure.

— Function: gst-structure-id-get-value (self <gst-structure>) (field unsigned-int) (ret <gvalue>)

Get the value of the field with GQuark field.

structure
a <gst-structure>
field
the <g-quark> of the field to get
ret
the <gvalue> corresponding to the field with the given name identifier.

— Function: gst-structure-id-set-value (self <gst-structure>) (field unsigned-int) (value <gvalue>)

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.

structure
a <gst-structure>
field
a <g-quark> representing a field
value
the new value of the field

— Function: gst-structure-get-value (self <gst-structure>) (fieldname mchars) (ret <gvalue>)

Get the value of the field with name fieldname.

structure
a <gst-structure>
fieldname
the name of the field to get
ret
the <gvalue> corresponding to the field with the given name.

— Function: gst-structure-set-value (self <gst-structure>) (fieldname mchars) (value <gvalue>)

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.

structure
a <gst-structure>
fieldname
the name of the field to set
value
the new value of the field

— Function: gst-structure-remove-field (self <gst-structure>) (fieldname mchars)

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

structure
a <gst-structure>
fieldname
the name of the field to remove

— Function: gst-structure-remove-all-fields (self <gst-structure>)

Removes all fields in a GstStructure.

structure
a <gst-structure>

— Function: gst-structure-get-field-type (self <gst-structure>) (fieldname mchars) (ret <gtype>)

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 <gst-structure>
fieldname
the name of the field
ret
the <gvalue> of the field

— Function: gst-structure-foreach (self <gst-structure>) (proc scm)

Calls the provided function once for each field in the <gst-structure>. The function must not modify the fields. Also see gst-structure-map-in-place.

structure
a <gst-structure>
func
a function to call for each field
user-data
private data
ret
TRUE if the supplied function returns TRUE For each of the fields, FALSE otherwise.

— Function: gst-structure-n-fields (self <gst-structure>) (ret int)

Get the number of fields in the structure.

structure
a <gst-structure>
ret
the number of fields in the structure

— Function: gst-structure-has-field (self <gst-structure>) (fieldname mchars) (ret bool)

Check if structure contains a field named fieldname.

structure
a <gst-structure>
fieldname
the name of a field
ret
TRUE if the structure contains a field with the given name

— Function: gst-structure-has-field-typed (self <gst-structure>) (fieldname mchars) (type <gtype>) (ret bool)

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

structure
a <gst-structure>
fieldname
the name of a field
type
the type of a value
ret
TRUE if the structure contains a field with the given name and type

— Function: gst-structure-get-boolean (self <gst-structure>) (fieldname mchars) (ret bool) (value bool)

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 <gst-structure>
fieldname
the name of a field
value
a pointer to a <gboolean> to set
ret
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.

— Function: gst-structure-get-int (self <gst-structure>) (fieldname mchars) (ret bool) (value int)

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.
Returns: ‘#t’ 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

structure
a <gst-structure>
fieldname
the name of a field
value
a pointer to an int to set
ret
‘#f’.

— Function: gst-structure-get-fourcc (self <gst-structure>) (fieldname mchars) (ret bool) (value unsigned-int32)

Sets the <gst-fourcc> pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.
Returns: TRUE if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a fourcc, this function

structure
a <gst-structure>
fieldname
the name of a field
value
a pointer to a <gst-fourcc> to set
ret
FALSE.

— Function: gst-structure-get-double (self <gst-structure>) (fieldname mchars) (ret bool) (value double)

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 <gst-structure>
fieldname
the name of a field
value
a pointer to a <gst-fourcc> to set
ret
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.

— Function: gst-structure-get-string (self <gst-structure>) (fieldname mchars) (ret mchars)

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 <gst-structure>
fieldname
the name of a field
ret
a pointer to the string or NULL when the field did not exist or did not contain a string.

— Function: gst-structure-get-date (self <gst-structure>) (fieldname mchars) (value <g-date**>) (ret bool)

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

structure
a <gst-structure>
fieldname
the name of a field
value
a pointer to a <g-date> to set
ret
FALSE.

— Function: gst-structure-get-clock-time (self <gst-structure>) (fieldname mchars) (value <gst-clock-time*>) (ret bool)

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.

structure
a <gst-structure>
fieldname
the name of a field
value
a pointer to a <gst-clock-time> to set
ret
TRUE if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a <gst-clock-time>, this function returns FALSE.

— Function: gst-structure-get-enum (self <gst-structure>) (fieldname mchars) (enumtype <gtype>) (ret bool) (value int)

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.

structure
a <gst-structure>
fieldname
the name of a field
enumtype
the enum type of a field
value
a pointer to an int to set
ret
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.

— Function: gst-structure-get-fraction (self <gst-structure>) (fieldname mchars) (ret bool) (value_numerator int) (value_denominator int)

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.

structure
a <gst-structure>
fieldname
the name of a field
value-numerator
a pointer to an int to set
value-denominator
a pointer to an int to set
ret
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.

— Function: gst-structure-map-in-place (self <gst-structure>) (func <gst-structure-map-func>) (user_data <gpointer>) (ret bool)

Calls the provided function once for each field in the <gst-structure>. In contrast to gst-structure-foreach, the function may modify but not delete the fields. The structure must be mutable.

structure
a <gst-structure>
func
a function to call for each field
user-data
private data
ret
TRUE if the supplied function returns TRUE For each of the fields, FALSE otherwise.

— Function: gst-structure-nth-field-name (self <gst-structure>) (index unsigned-int) (ret mchars)

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

structure
a <gst-structure>
index
the index to get the name of
ret
the name of the given field number

— Function: gst-structure-set-parent-refcount (self <gst-structure>) (refcount int)

Sets the parent_refcount field of <gst-structure>. This field is used to determine whether a structure is mutable or not. This function should only be called by code implementing parent objects of <gst-structure>, as described in the MT Refcounting section of the design documents.

structure
a <gst-structure>
refcount
a pointer to the parent's refcount

— Function: gst-structure-to-string (self <gst-structure>) (ret mchars)

Converts structure to a human-readable string representation.

structure
a <gst-structure>
ret
a pointer to string allocated by g-malloc. g-free after usage.

— Function: gst-structure-from-string (string mchars) (ret <gst-structure>)

Creates a <gst-structure> from a string representation. If end is not NULL, a pointer to the place inside the given string where parsing ended will be returned.

string
a string representation of a <gst-structure>.
end
pointer to store the end of the string in.
ret
a new <gst-structure> or NULL when the string could not be parsed. Free after usage.

— Function: gst-structure-fixate-field-boolean (self <gst-structure>) (field_name mchars) (target bool) (ret bool)

Fixates a <gst-structure> by changing the given field-name field to the given target boolean if that field is not fixed yet.

structure
a <gst-structure>
field-name
a field in structure
target
the target value of the fixation
ret
TRUE if the structure could be fixated

33 GstStructure

33.1 Overview

33.2 Usage