aboutsummaryrefslogtreecommitdiffstats
path: root/ns/ext/files
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2011-11-20 23:08:57 +0000
committerDavid Robillard <d@drobilla.net>2011-11-20 23:08:57 +0000
commit725d4a404b838da6b67d9da66228a1125bddef57 (patch)
treea1daab3d767c85b1b67ff3a9eb60d54721b2e5fc /ns/ext/files
parent5ae0165d6d0420e95e22c1451e319b9e83398c28 (diff)
downloadlv2-725d4a404b838da6b67d9da66228a1125bddef57.tar.xz
Lay out repository structure to match include and URI structure.
Treat lv2core like all the other specifications in gendoc.py.
Diffstat (limited to 'ns/ext/files')
l---------ns/ext/files/ext.pc.in1
-rw-r--r--ns/ext/files/files.h134
-rw-r--r--ns/ext/files/files.ttl115
-rw-r--r--ns/ext/files/manifest.ttl9
l---------ns/ext/files/waf1
l---------ns/ext/files/wscript1
6 files changed, 261 insertions, 0 deletions
diff --git a/ns/ext/files/ext.pc.in b/ns/ext/files/ext.pc.in
new file mode 120000
index 0000000..1cdad2a
--- /dev/null
+++ b/ns/ext/files/ext.pc.in
@@ -0,0 +1 @@
+../../../ext.pc.in \ No newline at end of file
diff --git a/ns/ext/files/files.h b/ns/ext/files/files.h
new file mode 100644
index 0000000..623587a
--- /dev/null
+++ b/ns/ext/files/files.h
@@ -0,0 +1,134 @@
+/*
+ Copyright 2010-2011 David Robillard <d@drobilla.net>
+
+ Permission to use, copy, modify, and/or distribute this software for any
+ purpose with or without fee is hereby granted, provided that the above
+ copyright notice and this permission notice appear in all copies.
+
+ THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+
+/**
+ @file files.h
+ C API for the LV2 Files extension <http://lv2plug.in/ns/ext/files>.
+*/
+
+#ifndef LV2_FILES_H
+#define LV2_FILES_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define LV2_FILES_URI "http://lv2plug.in/ns/ext/files"
+#define LV2_FILES_PATH_SUPPORT_URI LV2_FILES_URI "#pathSupport"
+#define LV2_FILES_NEW_FILE_SUPPORT_URI LV2_FILES_URI "#newFileSupport"
+
+typedef void* LV2_Files_Host_Data;
+
+/**
+ files:pathSupport feature struct.
+
+ To support this feature, the host MUST pass an LV2_Feature struct with @a
+ URI @ref LV2_FILES_PATH_SUPPORT_URI and @a data pointed to an instance of
+ this struct.
+*/
+typedef struct {
+
+ /**
+ Opaque host data.
+ */
+ LV2_Files_Host_Data host_data;
+
+ /**
+ 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* (*absolute_path)(LV2_Files_Host_Data host_data,
+ const char* abstract_path);
+
+} LV2_Files_Path_Support;
+
+/**
+ files:newFileSupport feature struct.
+
+ To support this feature, the host MUST pass an LV2_Feature struct with @a
+ URI @ref LV2_FILES_NEW_FILE_SUPPORT_URI and @a data pointed to an instance
+ of this struct.
+*/
+typedef struct {
+
+ /**
+ Opaque host data.
+ */
+ LV2_Files_Host_Data host_data;
+
+ /**
+ 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 LV2_Files_Path_Support::abstract_path 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_New_File_Support;
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* LV2_FILES_H */
diff --git a/ns/ext/files/files.ttl b/ns/ext/files/files.ttl
new file mode 100644
index 0000000..d3ff8a5
--- /dev/null
+++ b/ns/ext/files/files.ttl
@@ -0,0 +1,115 @@
+# LV2 Files Extension
+# Copyright 2010-2011 David Robillard <d@drobilla.net>
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+@prefix atom: <http://lv2plug.in/ns/ext/atom#> .
+@prefix doap: <http://usefulinc.com/ns/doap#> .
+@prefix files: <http://lv2plug.in/ns/ext/files#> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+<http://lv2plug.in/ns/ext/files>
+ a lv2:Specification ;
+ doap:name "LV2 Files" ;
+ doap:shortdesc "A standard for referring to files in plugin state." ;
+ doap:license <http://opensource.org/licenses/isc-license> ;
+ doap:release [
+ doap:revision "0.2" ;
+ doap:created "2011-04-05"
+ ] ;
+ doap:maintainer [
+ a foaf:Person ;
+ foaf:name "David Robillard" ;
+ foaf:homepage <http://drobilla.net/> ;
+ rdfs:seeAlso <http://drobilla.net/drobilla.rdf>
+ ] ;
+ lv2:documentation """
+<p>This extension provides a mechanism for plugins to portably refer to files
+in persistent plugin state (using the <a
+href="http://lv2plug.in/ns/ext/persist">LV2 Persist</a> extension), and create
+instance-local 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 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>This extension defines two features: files:newFileSupport allows plugins to
+create new files within an instance-specific namespace at any time (except in
+realtime contexts); while files:pathSupport allows plugins to refer to file
+paths in plugin state in a way transparent to the host.</p>
+
+<p>To create a new file, the plugin MUST request a path from the host using
+LV2_Files_New_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>To store a path in persistent state, the plugin MUST map it to an
+<q>abstract path</q> using LV2_Files_Path_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_Path_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:pathSupport a lv2:Feature ;
+ rdfs:label "Support for storing file paths in plugin state" ;
+ lv2:documentation """
+<p>This feature allows plugins to refer to pre-existing or newly created files
+in persistent plugin state in a portable way. To support this feature a host
+MUST pass a LV2_Files_Path_Support structure to the plugin's
+LV2_Descriptor::instantiate() method as an LV2_Feature with LV2_Feature::URI =
+LV2_FILES_PATH_SUPPORT_URI and LV2_Feature::data pointed to an instance of
+LV2_Files_Path_Support.</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:newFileSupport a lv2:Feature ;
+ rdfs:label "Support for creating new files" ;
+ lv2:documentation """
+<p>This feature allows plugins to create new files local to that plugin
+instance. To support this feature a host MUST pass a
+LV2_Files_New_File_Support structure to the plugin's
+LV2_Descriptor::instantiate() method as an LV2_Feature with LV2_Feature::URI =
+LV2_FILES_NEW_FILE_SUPPORT_URI and LV2_Feature::data pointed to an instance of
+LV2_Files_New_File_Support.</p>
+""" .
+
+files:AbstractPath a rdfs:Class ;
+ rdfs:label "File Path" ;
+ lv2:documentation """
+<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/ns/ext/files/manifest.ttl b/ns/ext/files/manifest.ttl
new file mode 100644
index 0000000..d0233c4
--- /dev/null
+++ b/ns/ext/files/manifest.ttl
@@ -0,0 +1,9 @@
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+<http://lv2plug.in/ns/ext/files>
+ a lv2:Specification ;
+ lv2:minorVersion 0 ;
+ lv2:microVersion 2 ;
+ rdfs:seeAlso <files.ttl> .
+
diff --git a/ns/ext/files/waf b/ns/ext/files/waf
new file mode 120000
index 0000000..917d5c5
--- /dev/null
+++ b/ns/ext/files/waf
@@ -0,0 +1 @@
+../../../waf \ No newline at end of file
diff --git a/ns/ext/files/wscript b/ns/ext/files/wscript
new file mode 120000
index 0000000..cf8cbae
--- /dev/null
+++ b/ns/ext/files/wscript
@@ -0,0 +1 @@
+../../../ext.wscript \ No newline at end of file