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.

Parameters

  • port_symbol – The symbol of the port.

  • user_data – The user_data passed to lilv_state_new_from_instance().

  • size – (Output) The size of the returned value.

  • 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.

Parameters

  • port_symbol – The symbol of the port.

  • user_data – The user_data passed to lilv_state_restore().

  • size – The size of value.

  • type – The URID of the type of value.

  • 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.