# Plugin State

typedef const void *(*LilvGetPortValueFunc)(const char *port_symbol, void *user_data, uint32_t *size, uint32_t *type)

  Function to get a port value.

  This function MUST set `size` and `type` appropriately.

  Param port_symbol:

    The symbol of the port.

  Param user_data:

    The user_data passed to `lilv_state_new_from_instance()`.

  Param size:

    (Output) The size of the returned value.

  Param type:

    (Output) The URID of the type of the returned value.

  Returns:

    A pointer to the port value.

typedef void (*LilvSetPortValueFunc)(const char *port_symbol, void *user_data, const void *value, uint32_t size, uint32_t type)

  Function to set a port value.

  Param port_symbol:

    The symbol of the port.

  Param user_data:

    The user_data passed to `lilv_state_restore()`.

  Param size:

    The size of `value`.

  Param type:

    The URID of the type of `value`.

  Param value:

    A pointer to the port value.

LilvState *lilv_state_new_from_world(LilvWorld *world, LV2_URID_Map *map, const LilvNode *node)

  Load a state snapshot from the world RDF model.

  This function can be used to load the default state of a plugin by passing the plugin URI as the `subject` parameter.

  Parameters:

    - world – The world.

    - map – URID mapper.

    - node – The subject of the state description (such as a preset URI).

  Returns:

    A new LilvState which must be freed with `lilv_state_free()`, or NULL.

LilvState *lilv_state_new_from_file(LilvWorld *world, LV2_URID_Map *map, const LilvNode *subject, const char *path)

  Load a state snapshot from a file.

  If `subject` is NULL, it is taken to be the URI of the file (`<>` in Turtle).

  This function parses the file separately to create the state, it does not parse the file into the world model, that is, the returned state is the only new memory consumed once this function returns.

  Parameters:

    - world – The world.

    - map – URID mapper.

    - subject – The subject of the state description (such as a preset URI).

    - path – The path of the file containing the state description.

  Returns:

    A new LilvState which must be freed with `lilv_state_free()`.

LilvState *lilv_state_new_from_string(LilvWorld *world, LV2_URID_Map *map, const char *str)

  Load a state snapshot from a string made by `lilv_state_to_string()`.

LilvState *lilv_state_new_from_instance(const LilvPlugin *plugin, LilvInstance *instance, LV2_URID_Map *map, const char *scratch_dir, const char *copy_dir, const char *link_dir, const char *save_dir, LilvGetPortValueFunc get_value, void *user_data, uint32_t flags, const LV2_Feature *const *features)

  Create a new state snapshot from a plugin instance.

  This function may be called simultaneously with any instance function (except discovery functions) unless the threading class of that function explicitly disallows this.

  To support advanced file functionality, there are several directory parameters. The multiple parameters are necessary to support saving an instance’s state many times, or saving states from multiple instances, while avoiding any duplication of data. For example, a host could pass the same `copy_dir` and `link_dir` for all plugins in a session (for example `session/shared/copy/` `session/shared/link/`), while the `save_dir` would be unique to each plugin instance (for example `session/states/state1.lv2` for one instance and `session/states/state2.lv2` for another instance). Simple hosts that only wish to save a single plugin’s state once may simply use the same directory for all of them, or pass NULL to not support files at all.

  If supported (via state:makePath passed to LV2_Descriptor::instantiate()), `scratch_dir` should be the directory where any files created by the plugin (for example during instantiation or while running) are stored. Any files here that are referred to in the state will be copied to preserve their contents at the time of the save. Lilv will assume any files within this directory (recursively) are created by the plugin and that all other files are immutable. Note that this function does not completely save the state, use `lilv_state_save()` for that.

  See state.h from the LV2 State extension for details on the `flags` and `features` parameters.

  Parameters:

    - plugin – The plugin this state applies to.

    - instance – An instance of `plugin`.

    - map – The map to use for mapping URIs in state.

    - scratch_dir – Directory of files created by the plugin earlier, or NULL. This is for hosts that support file creation at any time with state state:makePath. These files will be copied as necessary to `copy_dir` and not be referred to directly in state (a temporary directory is appropriate).

    - copy_dir – Directory of copies of files in `scratch_dir`, or NULL. This directory will have the same structure as `scratch_dir` but with possibly modified file names to distinguish revisions. This allows the saved state to contain the exact contents of the scratch file at save time, so that the state is not ruined if the file is later modified (for example, by the plugin continuing to record). This can be the same as `save_dir` to create a copy in the state bundle, but can also be a separate directory which allows multiple state snapshots to share a single copy if the file has not changed.

    - link_dir – Directory of links to external files, or NULL. A link will be made in this directory to any external files referred to in plugin state. In turn, links will be created in the save directory to these links (like save_dir/file => link_dir/file => /foo/bar/file). This allows many state snapshots to share a single link to an external file, so archival (for example, with `tar -h`) will not create several copies of the file. If this is not required, it can be the same as `save_dir`.

    - save_dir – Directory of files created by plugin during save (or NULL). This is typically the bundle directory later passed to `lilv_state_save()`.

    - get_value – Function to get port values (or NULL). If NULL, the returned state will not represent port values. This should only be NULL in hosts that save and restore port values via some other mechanism.

    - user_data – User data to pass to `get_value`.

    - flags – Bitwise OR of LV2_State_Flags values.

    - features – Features to pass LV2_State_Interface.save().

  Returns:

    A new LilvState which must be freed with `lilv_state_free()`.

void lilv_state_free(LilvState *state)

  Free `state`.

bool lilv_state_equals(const LilvState *a, const LilvState *b)

  Return true iff `a` is equivalent to `b`.

unsigned lilv_state_get_num_properties(const LilvState *state)

  Return the number of properties in `state`.

const LilvNode *lilv_state_get_plugin_uri(const LilvState *state)

  Get the URI of the plugin `state` applies to.

const LilvNode *lilv_state_get_uri(const LilvState *state)

  Get the URI of `state`.

  This may return NULL if the state has not been saved and has no URI.

const char *lilv_state_get_label(const LilvState *state)

  Get the label of `state`.

void lilv_state_set_label(LilvState *state, const char *label)

  Set the label of `state`.

int lilv_state_set_metadata(LilvState *state, uint32_t key, const void *value, size_t size, uint32_t type, uint32_t flags)

  Set a metadata property on `state`.

  This is a generic version of `lilv_state_set_label()`, which sets metadata properties visible to hosts, but not plugins. This allows storing useful information such as comments or preset banks.

  Parameters:

    - state – The state to set the metadata for.

    - key – The key to store `value` under (URID).

    - value – Pointer to the value to be stored.

    - size – The size of `value` in bytes.

    - type – The type of `value` (URID).

    - flags – LV2_State_Flags for `value`.

  Returns:

    Zero on success.

void lilv_state_emit_port_values(const LilvState *state, LilvSetPortValueFunc set_value, void *user_data)

  Enumerate the port values in a state snapshot.

  This function is a subset of `lilv_state_restore()` that only fires the `set_value` callback and does not directly affect a plugin instance. This is useful in hosts that need to retrieve the port values in a state snapshot for special handling.

  Parameters:

    - state – The state to retrieve port values from.

    - set_value – A function to receive port values.

    - user_data – User data to pass to `set_value`.

void lilv_state_restore(const LilvState *state, LilvInstance *instance, LilvSetPortValueFunc set_value, void *user_data, uint32_t flags, const LV2_Feature *const *features)

  Restore a plugin instance from a state snapshot.

  This will set all the properties of `instance`, if given, to the values stored in `state`. If `set_value` is provided, it will be called (with the given `user_data`) to restore each port value, otherwise the host must restore the port values itself (using lilv_state_get_port_value()) in order to completely restore `state`.

  If the state has properties and `instance` is given, this function is in the “instantiation” threading class, so it MUST NOT be called simultaneously with any function on the same plugin instance. If the state has no properties, only port values are set via `set_value`.

  See state.h from the LV2 State extension for details on the `flags` and `features` parameters.

  Parameters:

    - state – The state to restore, which must apply to the correct plugin.

    - instance – An instance of the plugin `state` applies to, or NULL.

    - set_value – A function to set a port value (may be NULL).

    - user_data – User data to pass to `set_value`.

    - flags – Bitwise OR of LV2_State_Flags values.

    - features – Features to pass LV2_State_Interface.restore().

int lilv_state_save(LilvWorld *world, LV2_URID_Map *map, LV2_URID_Unmap *unmap, const LilvState *state, const char *uri, const char *dir, const char *filename)

  Save state to a file.

  The format of state on disk is compatible with that defined in the LV2 preset extension, so this function may be used to save presets which can be loaded by any host.

  If `uri` is NULL, the preset URI will be a file URI, but the bundle can safely be moved (the state file will use `<>` as the subject).

  Parameters:

    - world – The world.

    - map – URID mapper.

    - unmap – URID unmapper.

    - state – State to save.

    - uri – URI of state, may be NULL.

    - dir – Path of the bundle directory to save into.

    - filename – Path of the state file relative to `dir`.

char *lilv_state_to_string(LilvWorld *world, LV2_URID_Map *map, LV2_URID_Unmap *unmap, const LilvState *state, const char *uri, const char *base_uri)

  Save state to a string.

  This function does not use the filesystem.

  Parameters:

    - world – The world.

    - map – URID mapper.

    - unmap – URID unmapper.

    - state – The state to serialize.

    - uri – URI for the state description (mandatory).

    - base_uri – Base URI for serialisation. Unless you know what you are doing, pass NULL for this, otherwise the state may not be restorable via `lilv_state_new_from_string()`.

int lilv_state_delete(LilvWorld *world, const LilvState *state)

  Unload a state from the world and delete all associated files.

  This function DELETES FILES/DIRECTORIES FROM THE FILESYSTEM! It is intended for removing user-saved presets, but can delete any state the user has permission to delete, including presets shipped with plugins.

  The rdfs:seeAlso file for the state will be removed. The entry in the bundle’s manifest.ttl is removed, and if this results in an empty manifest, then the manifest file is removed. If this results in an empty bundle, then the bundle directory is removed as well.

  Parameters:

    - world – The world.

    - state – State to remove from the system.