Spa Type Information

Spa has a type system that is represented by a set of arrays that contain spa_type_info structures. This type system is simple, yet complex to work with for a couple of reasons.

WirePlumber uses this API to access the spa type system, which makes some things easier to understand and work with. The main benefit of using this API is that it makes it easy to work with string representations of the types, allowing easier access from script bindings.

Type hierarchy

On the top level, there is a list of types like Int, Bool, String, Id, Object. These are called fundamental types (terms borrowed from GType). Fundamental types can be derived and therefore we can have other types that represent specific objects, for instance.

Enum and flag types are all represented with SPA_TYPE_Id. These types may have a list of possible values that one can select from (enums) or combine (flags). These values are accessed with the WpSpaIdTable API.

Object types can have fields. All objects always have a special "id" field, which is an enum. Its possible values can be given by wp_spa_type_get_object_id_values_table. Optionally, objects can also have other object-specific fields, which can be accessed with wp_spa_type_get_values_table.

Every object field or enum value is represented by a WpSpaIdValue. In the case of object fields, each field can be of a specific type, which is returned by wp_spa_id_value_get_value_type.

WpSpaType


Methods

wp_spa_type_get_object_id_values_table

WpSpaIdTable
wp_spa_type_get_object_id_values_table (WpSpaType type)

Object pods (see WpSpaPod) always have a special "id" field along with other fields that can be defined. This "id" field can only store values of a specific SPA_TYPE_Id type. This function returns the table that contains the possible values for that field.

Parameters:

type

the type id of an object type

Returns

the table with the values that can be stored in the special "id" field of an object of the given type


wp_spa_type_get_values_table

WpSpaIdTable
wp_spa_type_get_values_table (WpSpaType type)

Parameters:

type

a type id

Returns

the associated WpSpaIdTable that contains possible values or object fields for this type, or NULL


wp_spa_type_is_fundamental

gboolean
wp_spa_type_is_fundamental (WpSpaType type)

Parameters:

type

a type id

Returns

TRUE if the type has no parent, FALSE otherwise


wp_spa_type_is_id

gboolean
wp_spa_type_is_id (WpSpaType type)

Parameters:

type

a type id

Returns

TRUE if the type is a SPA_TYPE_Id, FALSE otherwise


wp_spa_type_is_object

gboolean
wp_spa_type_is_object (WpSpaType type)

Parameters:

type

a type id

Returns

TRUE if the type is a SPA_TYPE_Object, FALSE otherwise


wp_spa_type_name

const gchar*
wp_spa_type_name (WpSpaType type)

Parameters:

type

a type id

Returns

the complete name of the given type or NULL if type is invalid


wp_spa_type_parent

WpSpaType
wp_spa_type_parent (WpSpaType type)

Parameters:

type

a type id

Returns ( [transfer: none])

the direct parent type of the given type; if the type is fundamental (i.e. has no parent), the returned type is the same as type


Functions

wp_spa_type_from_name

WpSpaType
wp_spa_type_from_name (const gchar* name)

Looks up the type id from a given type name

Parameters:

name

the name to look up

Returns ( [transfer: none])

the corresponding type id or WP_SPA_TYPE_INVALID if not found


Functions

wp_spa_dynamic_id_table_register

WpSpaIdTable
wp_spa_dynamic_id_table_register (const gchar* name,
                                  const spa_type_info* values)

Registers an additional WpSpaIdTable in the spa type system. This is useful to add custom enumeration types.

Note that both name and values must be statically allocated, or otherwise guaranteed to be kept in memory until wp_spa_dynamic_type_deinit is called. No memory copy is done by this function.

Parameters:

name

the name of the id table

values

an array of spa_type_info that contains the values of the table

Returns

the new table


wp_spa_dynamic_type_deinit

wp_spa_dynamic_type_deinit ()

Deinitializes the spa type registry. You do not need to ever call this, unless you want to free memory at the end of the execution of a test, so that it doesn't show as leaked in the memory profiler.


wp_spa_dynamic_type_init

wp_spa_dynamic_type_init ()

Initializes the spa dynamic type registry. This allows registering new spa types at runtime. The spa type system still works if this function is not called.

Normally called by wp_init when WP_INIT_SPA_TYPES is passed in its flags.


wp_spa_dynamic_type_register

WpSpaType
wp_spa_dynamic_type_register (const gchar* name,
                              WpSpaType parent,
                              const spa_type_info* values)

Registers an additional type in the spa type system. This is useful to add a custom pod object type.

Note that both name and values must be statically allocated, or otherwise guaranteed to be kept in memory until wp_spa_dynamic_type_deinit is called. No memory copy is done by this function.

Parameters:

name

the name of the type

parent

the parent type

values

an array of spa_type_info that contains the values of the type, used only for Object types

Returns ( [transfer: none])

the new type


wp_spa_id_table_find_value

WpSpaIdValue
wp_spa_id_table_find_value (WpSpaIdTable table,
                            guint value)

Parameters:

table

the id table

value

a numeric value that is contained in the table

Returns ( [nullable])

the WpSpaIdValue associated with value, or NULL


wp_spa_id_table_find_value_from_name

WpSpaIdValue
wp_spa_id_table_find_value_from_name (WpSpaIdTable table,
                                      const gchar* name)

Parameters:

table

the id table

name

the full name of a value that is contained in the table

Returns ( [nullable])

the WpSpaIdValue associated with name, or NULL


wp_spa_id_table_find_value_from_short_name

WpSpaIdValue
wp_spa_id_table_find_value_from_short_name (WpSpaIdTable table,
                                            const gchar* short_name)

Parameters:

table

the id table

short_name

the short name of a value that is contained in the table

Returns ( [nullable])

the WpSpaIdValue associated with short_name, or NULL


wp_spa_id_table_from_name

WpSpaIdTable
wp_spa_id_table_from_name (const gchar* name)

Finds a WpSpaIdTable given its name. This name can either be the full type name of an object type, or the name of an enum (which is not(!!) a type).

For example, "Spa:Pod:Object:Param:Format" and "Spa:Enum:ParamId" are both valid table names.

Parameters:

name

the full name of an id table

Returns ( [nullable])

the associated table, or NULL


wp_spa_id_table_get_type

GType
wp_spa_id_table_get_type ()
Returns
No description available

wp_spa_id_table_new_iterator

WpIterator *
wp_spa_id_table_new_iterator (WpSpaIdTable table)

This function returns an iterator that allows you to iterate through the values associated with this table. The items in the iterator are of type WpSpaIdValue.

Parameters:

table

the id table

Returns

a WpIterator that iterates over WpSpaIdValue items


wp_spa_id_value_array_get_item_type

WpSpaType
wp_spa_id_value_array_get_item_type (WpSpaIdValue id,
                                     WpSpaIdTable * table)

If the value type of id is SPA_TYPE_Array, this function returns the type that is allowed to be contained inside the array.

When the returned type is (or is derived from) SPA_TYPE_Id or SPA_TYPE_Object, table is set to point to the WpSpaIdTable that contains the possible Id values / object fields.

Parameters:

id

an id value

table ( [out][optional])

the associated WpSpaIdTable

Returns ( [transfer: none])

the type that is allowed in the array, if id represents an object field that takes an array as value


wp_spa_id_value_from_name

WpSpaIdValue
wp_spa_id_value_from_name (const gchar* name)

Looks up an id value (enum, flag or object field) directly from its full name. For instance, "Spa:Enum:Direction:Input" will resolve to the id value that represents "Input" in the "Spa:Enum:Direction" enum.

Parameters:

name

the full name of an id value

Returns

the id value for name, or NULL if no such id value was found


wp_spa_id_value_from_number

WpSpaIdValue
wp_spa_id_value_from_number (const gchar* table_name,
                             guint id)

Looks up an id value given its container table_name and its numeric representation, id

Parameters:

table_name

the name of the WpSpaIdTable to look up the value in

id

the numeric representation of the value to look up

Returns

the id value or NULL if it was not found


wp_spa_id_value_from_short_name

WpSpaIdValue
wp_spa_id_value_from_short_name (const gchar* table_name,
                                 const gchar* short_name)

Looks up an id value given its container table_name and its short_name

Parameters:

table_name

the name of the WpSpaIdTable to look up the value in

short_name

the short name of the value to look up

Returns

the id value or NULL if it was not found


wp_spa_id_value_get_type

GType
wp_spa_id_value_get_type ()
Returns
No description available

wp_spa_id_value_get_value_type

WpSpaType
wp_spa_id_value_get_value_type (WpSpaIdValue id,
                                WpSpaIdTable * table)

Returns the value type associated with this WpSpaIdValue. This information is useful when id represents an object field, which can take a value of an arbitrary type.

When the returned type is (or is derived from) SPA_TYPE_Id or SPA_TYPE_Object, table is set to point to the WpSpaIdTable that contains the possible Id values / object fields.

Parameters:

id

an id value

table ( [out][optional])

the associated WpSpaIdTable

Returns ( [transfer: none])

the value type associated with id


wp_spa_id_value_name

const gchar*
wp_spa_id_value_name (WpSpaIdValue id)

Parameters:

id

an id value

Returns

the full name of this id value


wp_spa_id_value_number

guint
wp_spa_id_value_number (WpSpaIdValue id)

Parameters:

id

an id value

Returns

the numeric representation of this id value


wp_spa_id_value_short_name

const gchar*
wp_spa_id_value_short_name (WpSpaIdValue id)

Parameters:

id

an id value

Returns

the short name of this id value


Constants

WP_TYPE_SPA_ID_TABLE

#define WP_TYPE_SPA_ID_TABLE (wp_spa_id_table_get_type ())

WP_TYPE_SPA_ID_VALUE

#define WP_TYPE_SPA_ID_VALUE (wp_spa_id_value_get_type ())

Aliases

WpSpaIdTable

typedef gconstpointer WpSpaIdTable

WpSpaIdValue

typedef gconstpointer WpSpaIdValue

The results of the search are