# 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_SPA_TYPE_INVALID 0xffffffff

    Type id representing an invalid SPA type.

  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