WpObject — WirePlumber 0.5.17 documentation

# WpObject

`WpObject` is the base class of most WirePlumber objects — nodes, devices, links, metadata, session items and so on. It binds the WpObject C API.

Its distinguishing feature is the features mechanism. A newly created object is not immediately usable in full: proxies to PipeWire objects, for example, start out knowing only their id, and additional information has to be requested and awaited. Features name the pieces of functionality that can be activated, and activation is asynchronous.

Scripts do not normally construct `WpObject` directly; they receive objects from an ObjectManager (already activated, as requested by the object manager) or create a specific subclass such as `Node()` or `SpaDevice()`.

## Activation

Object.activate(self, features, callback)

  Binds `wp_object_activate()`

  Requests activation of the given features. This is asynchronous: the object is only usable for those features once callback has been called successfully.

      device:activate (Feature.SpaDevice.ENABLED, function (dev, err)
        if err then
          log:warning (dev, "failed to activate: " .. err)
          return
        end
        -- the device is now enabled
      end)

  Parameters:

    - features (integer) -- a bitmask of the features to activate; see the constants below

    - callback (function) -- (optional) called when activation completes, as `callback(object, error)`; error is nil on success and an error message string on failure

Object.deactivate(self, features)

  Binds `wp_object_deactivate()`

  Deactivates the given features, releasing whatever resources they hold.

  Parameters:

    features (integer) -- a bitmask of the features to deactivate

Object.get_active_features(self)

  Binds `wp_object_get_active_features()`

  Returns:

    a bitmask of the features that are currently active

  Return type:

    integer

Object.get_supported_features(self)

  Binds `wp_object_get_supported_features()`

  Returns:

    a bitmask of the features that this object is able to activate

  Return type:

    integer

## Feature constants

Individual features are named by the `Feature` table, grouped by the object type that supports them:

Constant | Applies to
--- | ---
`Feature.Proxy.BOUND` | any proxy
`Feature.PipewireObject.INFO` | any PipeWire object
`Feature.PipewireObject.PARAM_PROPS` | objects with a Props param
`Feature.PipewireObject.PARAM_FORMAT` | objects with a Format param
`Feature.PipewireObject.PARAM_PROFILE` | devices
`Feature.PipewireObject.PARAM_PORT_CONFIG` | nodes
`Feature.PipewireObject.PARAM_ROUTE` | devices
`Feature.SpaDevice.ENABLED` | SpaDevice
`Feature.Node.PORTS` | Node
`Feature.Metadata.DATA` | Metadata
`Feature.SessionItem.ACTIVE` | SessionItem
`Feature.SessionItem.EXPORTED` | SessionItem

The `Features` table provides convenient combinations:

Constant | Meaning
--- | ---
`Features.ALL` | all features the object supports
`Features.PipewireObject.MINIMAL` | `Proxy.BOUND` plus `PipewireObject.INFO`

Since features are a bitmask, they are combined with the bitwise or operator:

    node:activate (Features.PipewireObject.MINIMAL | Feature.Node.PORTS,
        function (n, err) --[[ ... ]] end)