diff options
Diffstat (limited to 'ns/ext/files')
| l--------- | ns/ext/files/ext.pc.in | 1 | ||||
| -rw-r--r-- | ns/ext/files/files.h | 134 | ||||
| -rw-r--r-- | ns/ext/files/files.ttl | 115 | ||||
| -rw-r--r-- | ns/ext/files/manifest.ttl | 9 | ||||
| l--------- | ns/ext/files/waf | 1 | ||||
| l--------- | ns/ext/files/wscript | 1 |
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 |