Spa Device

struct WpSpaDevice

A WpSpaDevice allows running a spa_device object locally, loading the implementation from a SPA factory. This is useful to run device monitors inside the session manager and have control over creating the actual nodes that the spa_device requests to create.

To enable the spa device, call wp_object_activate() requesting WP_SPA_DEVICE_FEATURE_ENABLED.

For actual devices (not device monitors) it also possible and desirable to export the device to PipeWire, which can be done by requesting WP_PROXY_FEATURE_BOUND from wp_object_activate(). When exporting, the export should be done before enabling the device, by requesting both features at the same time.

GObject Properties

properties

Properties of the spa device

WpProperties *

G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY

spa-device-handle

The spa device handle

gpointer

G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY

GObject Signals

create-object

void
create_object_callback (WpSpaDevice * self,
                        guint id,
                        gchar * type,
                        gchar * factory,
                        WpProperties * properties,
                        gpointer user_data)

This signal is emitted when the device is creating a managed object The handler is expected to actually construct the object using the requested SPA factory and with the given properties. The handler should then store the object with wp_spa_device_store_managed_object. The WpSpaDevice will later unref the reference stored by this function when the managed object is to be destroyed.

Parameters:

id - the id of the managed object
type - the SPA type that the managed object should have
factory - the name of the SPA factory to use to construct the managed object
properties - additional properties that the managed object should have

Flags: G_SIGNAL_RUN_FIRST

object-removed

void
object_removed_callback (WpSpaDevice * self,
                         guint id,
                         gpointer user_data)

This signal is emitted when the device has deleted a managed object. The handler may optionally release additional resources associated with this object.

It is not necessary to call wp_spa_device_store_managed_object() to remove the managed object, as this is done internally after this signal is fired.

Parameters:

id - the id of the managed object

Flags: G_SIGNAL_RUN_FIRST

enum WpSpaDeviceFeatures

Flags to be used as WpObjectFeatures for WpSpaDevice.

Values:

enumerator WP_SPA_DEVICE_FEATURE_ENABLED = (WP_PROXY_FEATURE_CUSTOM_START << 0): enables a spa device

WpSpaDevice *wp_spa_device_new_wrap(WpCore *core, gpointer spa_device_handle, WpProperties *properties)

Constructs an SPA Device object from an existing device handle.

Parameters:

core – the wireplumber core
spa_device_handle – the spa device handle
properties – (nullable) (transfer full): additional properties of the device

Returns:

(transfer full): A new WpSpaDevice

WpSpaDevice *wp_spa_device_new_from_spa_factory(WpCore *core, const gchar *factory_name, WpProperties *properties)

Constructs a SPA_TYPE_INTERFACE_Device by loading the given SPA factory_name.

To export this device to the PipeWire server, you need to call wp_object_activate() requesting WP_PROXY_FEATURE_BOUND and wait for the operation to complete.

Parameters:

core – the wireplumber core
factory_name – the name of the SPA factory
properties – (nullable) (transfer full): properties to be passed to device constructor

Returns:

(nullable) (transfer full): A new WpSpaDevice wrapping the device that was constructed by the factory, or NULL if the factory does not exist or was unable to construct the device

WpProperties *wp_spa_device_get_properties(WpSpaDevice *self)

Gets the properties of this device.

Parameters:

self – the spa device

Returns:

(transfer full): the device properties

WpIterator *wp_spa_device_new_managed_object_iterator(WpSpaDevice *self)

Iterates through all the objects managed by this device.

Since: 0.4.11

Parameters:

self – the spa device

Returns:

(transfer full): a WpIterator that iterates over all the objects managed by this device

GObject *wp_spa_device_get_managed_object(WpSpaDevice *self, guint id)

Gets one of the objects managed by this device.

Parameters:

self – the spa device
id – the (device-internal) id of the object to get

Returns:

(transfer full): the managed object associated with id

void wp_spa_device_store_managed_object(WpSpaDevice *self, guint id, GObject *object)

Stores or removes a managed object into/from a device.

Parameters:

self – the spa device
id – the (device-internal) id of the object
object – (transfer full) (nullable): the object to store or NULL to remove the managed object associated with id

void wp_spa_device_set_managed_pending(WpSpaDevice *self, guint id)

Marks a managed object id pending.

When an object id is pending, Props from received ObjectConfig events for the id are saved. When wp_spa_device_store_managed_object later sets an object for the id, the saved Props are immediately set on the object and pending status is cleared.

If an object is already set for the id, this has no effect.

Parameters:

self – the spa device
id – the (device-internal) id of the object

WP_TYPE_SPA_DEVICE (wp_spa_device_get_type ()): The WpSpaDevice GType.