Spa Type Information

group wpspatype

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

Defines

WP_TYPE_SPA_TYPE (wp_spa_type_get_type ()): The WpSpaType GType.

WP_TYPE_SPA_ID_TABLE (wp_spa_id_table_get_type ()): The WpSpaIdTable GType.

WP_TYPE_SPA_ID_VALUE (wp_spa_id_value_get_type ()): The WpSpaIdValue GType.

Typedefs

typedef guint32 WpSpaType

typedef gconstpointer WpSpaIdTable

typedef gconstpointer WpSpaIdValue

Functions

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

WpSpaType wp_spa_type_parent(WpSpaType type)

Gets the parent type of an SPA 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

const gchar *wp_spa_type_name(WpSpaType type)

Gets the name of an SPA type.

Parameters

type – a type id

Returns

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

gboolean wp_spa_type_is_fundamental(WpSpaType type)

Checks if an SPA type is a fundamental type.

Parameters

type – a type id

Returns

TRUE if the type has no parent, FALSE otherwise

gboolean wp_spa_type_is_id(WpSpaType type)

Checks if an SPA type is an Id type.

Parameters

type – a type id

Returns

TRUE if the type is a SPA_TYPE_Id, FALSE otherwise

gboolean wp_spa_type_is_object(WpSpaType type)

Checks if an SPA type is an Object type.

Parameters

type – a type id

Returns

TRUE if the type is a SPA_TYPE_Object, FALSE otherwise

WpSpaIdTable wp_spa_type_get_object_id_values_table(WpSpaType type)

Gets the table with the values that can be stored in the special “id” field of an object of the given 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

WpSpaIdTable wp_spa_type_get_values_table(WpSpaType type)

Gets the values table of an SPA type.

Parameters

type – a type id

Returns

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

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

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

WpSpaIdValue wp_spa_id_table_find_value(WpSpaIdTable table, guint value)

Finds a value in an SPA Id table.

Parameters

table – the id table
value – a numeric value that is contained in the table

Returns

(nullable): the WpSpaIdValue associated with value, or NULL

WpSpaIdValue wp_spa_id_table_find_value_from_name(WpSpaIdTable table, const gchar *name)

Finds a named value in an SPA Id table.

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

WpSpaIdValue wp_spa_id_table_find_value_from_short_name(WpSpaIdTable table, const gchar *short_name)

Finds a short named value in an SPA Id table.

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

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

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

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

guint wp_spa_id_value_number(WpSpaIdValue id)

Gets the numeric value of an id value.

Parameters

id – an id value

Returns

the numeric representation of this id value

const gchar *wp_spa_id_value_name(WpSpaIdValue id)

Gets the name of an id value.

Parameters

id – an id value

Returns

the full name of this id value

const gchar *wp_spa_id_value_short_name(WpSpaIdValue id)

Gets the short name of an id value.

Parameters

id – an id value

Returns

the short name of this id value

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

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

void wp_spa_dynamic_type_init(void)

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.

void wp_spa_dynamic_type_deinit(void)

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.

WpSpaType wp_spa_dynamic_type_register(const gchar *name, WpSpaType parent, const struct 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

WpSpaIdTable wp_spa_dynamic_id_table_register(const gchar *name, const struct 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

Variables

static const WpSpaType WP_SPA_TYPE_INVALID = 0xffffffff: Type id representing an invalid SPA type.