Function lilv_sys::lilv_state_new_from_instance

pub unsafe extern "C" fn lilv_state_new_from_instance(
    plugin: *const LilvPlugin, 
    instance: *mut LilvInstance, 
    map: *mut LV2_URID_Map, 
    file_dir: *const c_char, 
    copy_dir: *const c_char, 
    link_dir: *const c_char, 
    save_dir: *const c_char, 
    get_value: LilvGetPortValueFunc, 
    user_data: *mut c_void, 
    flags: u32, 
    features: *const *const LV2_Feature
) -> *mut LilvState

Create a new state snapshot from a plugin instance.

@param plugin The plugin this state applies to.

@param instance An instance of plugin.

@param map The map to use for mapping URIs in state.

@param file_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).

@param copy_dir Directory of copies of files in file_dir (or NULL). This directory will have the same structure as file_dir but with possibly modified file names to distinguish different revisions. If you only care about saving one state snapshot, it can be the same as save_dir. Plugin state will refer to files in this directory.

@param save_dir Directory of files created by plugin during save (or NULL). If the state will be saved, this should be the bundle directory later passed to lilv_state_save().

@param 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.

@param user_data User data to pass to get_value.

@param 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 (e.g. 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 (e.g. with tar -h) will not create several copies of the file. If this is not required, it can be the same as save_dir.

@param flags Bitwise OR of LV2_State_Flags values.

@param features Features to pass LV2_State_Interface.save().

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

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. Simple hosts that only wish to save a single plugins state once may simply use the same directory for all of them (or pass NULL to not support files at all). The multiple parameters are necessary to support saving an instances state many times while avoiding any duplication of data.

If supported (via state:makePath passed to LV2_Descriptor::instantiate()), file_dir should be the directory where any files created by the plugin (not during save time, e.g. during instantiation) are stored. These files will be copied to preserve their state at this time.plugin-created files are stored. Lilv will assume any files within this directory (recursively) are created by the plugin and all other files are immutable. Note that this function does not 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.