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
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
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
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
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
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
the complete name of the given type or NULL if type is invalid
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
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
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
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
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
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
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
the associated table, or NULL
wp_spa_id_table_get_type
GType wp_spa_id_table_get_type ()
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
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.
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
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
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
the id value or NULL if it was not found
wp_spa_id_value_get_type
GType wp_spa_id_value_get_type ()
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.
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
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
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
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