State — WirePlumber 0.5.17 documentation

# State

Persistent state is how WirePlumber remembers things across restarts: which profile a device had, which node was the default, what volume a stream was last set to.

`State` binds the WpState C API and stores a set of key/value pairs in a file under the user's state directory (see Locations of WirePlumber's files). `StateMetadata` additionally mirrors the stored values into a PipeWire metadata object, so that they can be inspected and cleared with `pw-metadata`.

## State

State(name)

  Binds `wp_state_new()`

  Creates a state object backed by the state file called name.

  Parameters:

    name (string) -- the name of the state

  Returns:

    the new state object

  Return type:

    State

State.load(self)

  Binds `wp_state_load()`

  Loads the contents of the state file.

  Returns:

    the stored key/value pairs

  Return type:

    Properties, see Properties

State.save(self, properties)

  Binds `wp_state_save()`

  Writes properties to the state file, replacing its previous contents.

  Parameters:

    properties -- a table or Properties object

  Returns:

    true on success, plus an error message string if it failed

  Return type:

    boolean, string

State.save_after_timeout(self, properties)

  Binds `wp_state_save_after_timeout()`

  The same as `State.save()`, but delayed by a short timeout, and coalescing repeated calls into a single write. This is what the shipped scripts use, so that a burst of changes does not cause a burst of disk writes.

  Parameters:

    properties -- a table or Properties object

State.clear(self)

  Binds `wp_state_clear()`

  Deletes the state file.

## StateMetadata

StateMetadata(name)

  Binds `wp_state_metadata_new()`

  Creates a state object that also exposes its contents as a PipeWire metadata object named name.

  Parameters:

    name (string) -- the name of the state and of the metadata object

  Returns:

    the new state metadata object

  Return type:

    StateMetadata

StateMetadata.get(self, key)

  Binds `wp_state_metadata_get()`

  Parameters:

    key (string) -- the key to look up

  Returns:

    the stored value, or nil

  Return type:

    string

StateMetadata.set(self, key, value)

  Binds `wp_state_metadata_set()`

  Stores a value. Passing no value removes the key.

  Parameters:

    - key (string) -- the key to store under

    - value (string) -- (optional) the value to store

StateMetadata.clear(self)

  Binds `wp_state_metadata_clear()`

  Removes all the stored values.

The metadata object that `StateMetadata` exports is created in the same way as one created directly with `ImplMetadata`; see PipeWire Proxies.