aboutsummaryrefslogtreecommitdiffstats
path: root/ext
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2011-04-03 01:41:08 +0000
committerDavid Robillard <d@drobilla.net>2011-04-03 01:41:08 +0000
commitf738ee3d9fa250d2ffad031d05663f888df56130 (patch)
tree4e850b09a79fedcc6c4305ad1800fa69ea0dbce0 /ext
parent22a9dc0354eb1eb6b764b57d88561879c7731600 (diff)
downloadlv2-f738ee3d9fa250d2ffad031d05663f888df56130.tar.xz
Sensible, working files extension.
Diffstat (limited to 'ext')
-rw-r--r--ext/files.lv2/files.h90
-rw-r--r--ext/files.lv2/files.ttl93
-rw-r--r--ext/files.lv2/manifest.ttl2
3 files changed, 125 insertions, 60 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" */
diff --git a/ext/files.lv2/files.ttl b/ext/files.lv2/files.ttl
index 6b2b3ca..85ac314 100644
--- a/ext/files.lv2/files.ttl
+++ b/ext/files.lv2/files.ttl
@@ -31,6 +31,10 @@
<http://lv2plug.in/ns/ext/files>
a lv2:Specification ;
doap:name "LV2 Files" ;
+ doap:release [
+ doap:revision "0.1" ;
+ doap:created "2011-04-02"
+ ] ;
doap:maintainer [
a foaf:Person ;
foaf:name "David Robillard" ;
@@ -38,56 +42,63 @@
rdfs:seeAlso <http://drobilla.net/drobilla.rdf>
] ;
lv2:documentation """
-<p>This extension provides a mechanism for plugins to create new files for
-storing arbitrary data (e.g. waveforms), which can be persisted using
-the <a href="http://lv2plug.in/ns/ext/persist">LV2 Persist</a> extension.
-This allows plugins to work with potentially very large data via files,
-and save/restore these files across plugin instances.</p>
+<p>This extension provides a mechanism for plugins to use files and portably
+refer to files in persistent plugin state (using the <a
+href="http://lv2plug.in/ns/ext/persist">LV2 Persist</a> extension). A facility
+is also provided to allow plugins to create new files in host-defined
+locations, e.g. for recording.</p>
<p>The motivating idea behind this extension is that all details of file
-management MUST be handled by the host in whatever way is most appropriate for
-that host, since hosts may have very different requirements. Plugins MUST NOT
-make any assumption about filesystem locations beyond what is explicitly
-guaranteed by this extension.</p>
+management MUST be handled by the host since different hosts may have very
+different requirements. Plugins MUST NOT make any assumption about file system
+locations beyond what is explicitly guaranteed by this extension.</p>
-<p>To create a new file, plugins request a filename from the host. This way,
-the host is aware of files used by the plugin and can use an appropriate
-location for them that the plugin alone could not know (e.g. using an
-appropriate disk volume for recording).</p>
+<p>To create a new file, the plugin MUST request a path from the host using
+LV2_Files_File_Support::new_file_path(). Thus, the host may choose an
+appropriate location for the file (e.g. a writable path on the appropriate disk
+volume or a path within a session directory) using information not available to
+the plugin.</p>
-<p>Plugins MAY also use pre-existing files from elsewhere on the filesystem.
-Using the LV2 Persist extension, the host can save both these types of files
-in an appropriate way (by e.g. storing a link, or copying the file to export
-or archive a project).</p>
-""" .
+<p>To store a path in persistent state, the plugin MUST map it to an
+<q>abstract path</q> using LV2_Files_File_Support::abstract_path(). To use a
+path loaded from persistent state, the plugin MUST map the (abstract) path to
+an absolute path using LV2_Files_File_Support::absolute_path(). Thus, the host
+can manage all paths used in a session and support exporting sessions to a
+portable self-contained format for archival or distribution.</p> """ .
files:fileSupport a lv2:Feature ;
- rdfs:label "Support for plugin-created files" ;
- lv2:documentation """
-
-<p>This feature allows plugins to use pre-existing or newly created files, and
-persist them (e.g. across project saves and restores). If a host supports this
-feature it passes a LV2_Files_FileSupport structure to the plugins instantiate
-method as a feature (with URI http://lv2plug.in/ns/ext/files#FileSupport). This
-structure provides a function the plugin can use to create new file names. If
-and only if the host supports this feature, the plugin MAY files and restore
-values of type LV2_FILES_FILENAME.</p>
+ rdfs:label "Support for files in plugin state" ;
+ lv2:documentation """
+<p>This feature allows plugins to use pre-existing or newly created files and
+refer to them in persistent state. To support this feature a host MUST pass a
+LV2_Files_File_Support structure to the plugin's LV2_Descriptor::instantiate()
+method as an LV2_Feature with LV2_Feature::URI =
+<q>http://lv2plug.in/ns/ext/files#fileSupport</q> and LV2_Feature::data pointed
+to an instance of LV2_Files_File_Support.</p>
-<p>A plugin SHOULD use this facility to create any new files it may need
-(e.g. samples, waveforms for recording). Plugins MUST NOT expect their
-state to be correctly restored if they do not use this mechanism to
-create new files.</p>
+<p>Plugins MUST use the functions provided by this feature to handle
+<em>all</em> paths saved to, or restored from, persistent plugin state;
+otherwise broken and/or non-portable state will silently be created resulting
+in a broken user experience.</p>
""" .
-files:FilePath a atom:AtomType ;
+files:AbstractPath a rdfs:class ;
rdfs:label "File Path" ;
lv2:documentation """
-The full path to a file on the local filesystem. The format of a
-files:filePath is a C string (escaped or otherwise restricted in whatever way
-necessary for the system). This URI (http://lv2plug.in/ns/ext/files#FilePath),
-mapped to an integer, should be used as the <code>type</code> parameter with
-the LV2 Persist extension to persist a file. When persisting a files:FilePath,
-the plugin MUST NOT assume that the same path will be restored (i.e. the
-host MAY choose to store the file elsewhere). The plugin may, of course,
-assume that the actual contents of the file are equivalent when restored.
+<p>An abstract path to a file in persistent plugin state.</p>
+
+<p>The format of a files:AbstractPath is a C string escaped or otherwise
+restricted in a system-specific manner. This URI,
+<q>http://lv2plug.in/ns/ext/files#AbstractPath</q>, mapped to an integer,
+should be used as the <code>type</code> parameter to a
+LV2_Persist_Store_Function; and will likewise be returned by the corresponding
+call to a LV2_Persist_Retrieve_Function.</p>
+
+<p>Abstract paths reside in a namespace specific to a plugin instance.
+Typical hosts are expected to implement this by giving each plugin instance its
+own state directory.</p>
+
+<p>When storing and retrieving an abstract path, the plugin MUST NOT assume the
+same path will be restored. However, the restored path will refer to a file
+with equivalent contents to the original.</p>
""" .
diff --git a/ext/files.lv2/manifest.ttl b/ext/files.lv2/manifest.ttl
index 7f572d9..08c3ef2 100644
--- a/ext/files.lv2/manifest.ttl
+++ b/ext/files.lv2/manifest.ttl
@@ -3,5 +3,7 @@
<http://lv2plug.in/ns/ext/files>
a lv2:Specification ;
+ lv2:minorVersion 0 ;
+ lv2:microVersion 1 ;
rdfs:seeAlso <files.ttl> .