aboutsummaryrefslogtreecommitdiffstats
path: root/ext/files.lv2/files.h
diff options
context:
space:
mode:
Diffstat (limited to 'ext/files.lv2/files.h')
-rw-r--r--ext/files.lv2/files.h90
1 files changed, 71 insertions, 19 deletions
diff --git a/ext/files.lv2/files.h b/ext/files.lv2/files.h
index 4b93331..2ffb964 100644
--- a/ext/files.lv2/files.h
+++ b/ext/files.lv2/files.h
@@ -32,15 +32,16 @@
extern "C" {
#endif
-#define LV2_FILES_URI "http://lv2plug.in/ns/ext/files"
+#define LV2_FILES_URI "http://lv2plug.in/ns/ext/files"
+#define LV2_FILES_FILE_SUPPORT_URI LV2_FILES_URI "#fileSupport"
-typedef void* LV2_Files_FileSupport_Data;
+typedef void* LV2_Files_Host_Data;
/**
- files:FileSupport feature struct.
+ files:fileSupport feature struct.
To support this feature, the host MUST pass an LV2_Feature struct with @a
- URI "http://lv2plug.in/ns/ext/files#fileSupport" and @ data pointed to an
+ URI "http://lv2plug.in/ns/ext/files#fileSupport" and @a data pointed to an
instance of this struct.
*/
typedef struct {
@@ -48,23 +49,74 @@ typedef struct {
/**
Opaque host data.
*/
- LV2_Files_FileSupport_Data data;
-
+ LV2_Files_Host_Data host_data;
+
/**
- Return the full path that should be used for a file owned by this
- plugin called @a name. The plugin can assume @a name belongs to a
- namespace dedicated to that plugin instance (i.e. hosts MUST ensure
- this, e.g. by giving each plugin instance its own files directory).
-
- @param data MUST be the @a data member of this struct.
- @param name The name of the file.
- @return A newly allocated path which the plugin may use to create a new
- file. The plugin is responsible for freeing the returned string.
+ Map an absolute path to an abstract path for use in plugin state.
+ @param host_data MUST be the @a host_data member of this struct.
+ @param absolute_path The absolute path of a file.
+ @return An abstract path suitable for use in plugin state.
+
+ The plugin MUST use this function to map any paths that will be stored
+ in plugin state. The returned value is an abstract path which MAY not
+ be an actual file system path; @ref absolute_path MUST be used to map it
+ to an actual path in order to use the file.
+
+ Hosts MAY map paths in any way (e.g. by creating symbolic links within
+ the plugin's state directory or storing a list of referenced files for
+ later export). Plugins MUST NOT make any assumptions about abstract
+ paths except that they can be mapped to an absolute path using @ref
+ absolute_path. Particularly when restoring from state, this absolute
+ path MAY not be the same as the original absolute path, but the host
+ MUST guarantee it refers to a file with contents equivalent to the
+ original.
+
+ This function may only be called within the context of
+ LV2_Persist.save() or LV2_Persist.restore(). The caller is responsible
+ for freeing the returned value.
+ */
+ char* (*abstract_path)(LV2_Files_Host_Data host_data,
+ const char* absolute_path);
+
+ /**
+ Map an abstract path from plugin state to an absolute path.
+ @param host_data MUST be the @a host_data member of this struct.
+ @param abstract_path An abstract path (e.g. a path from plugin state).
+ @return An absolute file system path.
+
+ Since abstract paths are not necessarily actual file paths (or at least
+ not necessarily absolute paths), this function MUST be used in order to
+ actually open or otherwise use the file referred to by an abstract path.
+
+ This function may only be called within the context of
+ LV2_Persist.save() or LV2_Persist.restore(). The caller is responsible
+ for freeing the returned value.
*/
- char* new_file_path(LV2_Files_FileSupport_Data data,
- const char* name);
-
-} LV2_Files_FileSupport;
+ char* (*absolute_path)(LV2_Files_Host_Data host_data,
+ const char* abstract_path);
+
+
+ /**
+ Return an absolute path the plugin may use to create a new file.
+ @param host_data MUST be the @a host_data member of this struct.
+ @param relative_path The relative path of the file.
+ @return The absolute path to use for the new file.
+
+ The plugin can assume @a relative_path is relative to a namespace
+ dedicated to that plugin instance; hosts MUST ensure this, e.g. by
+ giving each plugin instance its own state directory. The returned path
+ is absolute and thus suitable for creating and using a file, but NOT
+ suitable for storing in plugin state (it MUST be mapped to an abstract
+ path using @ref abstract_path in order to do so).
+
+ This function may be called from any non-realtime context. The caller
+ is responsible for freeing the returned value.
+ */
+ char* (*new_file_path)(LV2_Files_Host_Data host_data,
+ const char* relative_path);
+
+
+} LV2_Files_File_Support;
#ifdef __cplusplus
} /* extern "C" */