Spa Device — WirePlumber 0.5.17 documentation

# 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

  Remark

  When the "client-context" component is loaded, which is the case in the default daemon configuration, the SPA handle is loaded in a secondary `pw_context` that runs on its own thread, so that the device is not affected by anything that blocks WirePlumber's main loop. The WpSpaDevice itself stays on the thread that created it: all the signals below are emitted there, in the order in which the `spa_device` emitted them, and wp_spa_device_enum_params_sync() and wp_spa_device_set_param() remain synchronous. Note, though, that the signals are then emitted asynchronously, so a handler may run after the call that caused the event has returned.

  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_enum_params_sync(WpSpaDevice *self, const gchar *id, WpSpaPod *filter)

  This method can be used to retrieve object parameters of the spa device synchronously because the spa device always runs locally.

  Since

    0.5.15

  Parameters:

    - self -- the spa device

    - id -- the parameter id to enumerate

    - filter -- (nullable): a param filter or NULL

  Returns:

    (transfer full) (nullable): an iterator to iterate over cached parameters, or NULL if parameters for this id are not cached; the items in the iterator are WpSpaPod

gboolean wp_spa_device_set_param(WpSpaDevice *self, const gchar *id, guint32 flags, WpSpaPod *param)

  Sets a parameter on the spa device.

  Since

    0.5.15

  Parameters:

    - self -- the pipewire object

    - id -- the parameter id to set

    - flags -- optional flags or 0

    - param -- (transfer full): the parameter to set

  Returns:

    TRUE on success, FALSE if setting the param failed

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.