aboutsummaryrefslogtreecommitdiffstats
path: root/ext/files.lv2/files.ttl
blob: 85ac31456c866541d4ef8fdd08201b2d83175211 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
# LV2 Files Extension
# Copyright 2010-2011 David Robillard <d@drobilla.net>
# 
# Permission is hereby granted, free of charge, to any person obtaining a
# copy of this software and associated documentation files (the "Software"),
# to deal in the Software without restriction, including without limitation
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
# and/or sell copies of the Software, and to permit persons to whom the
# Software is furnished to do so, subject to the following conditions:
# 
# The above copyright notice and this permission notice shall be included
# in all copies or substantial portions of the Software.
# 
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
# OTHER DEALINGS IN THE 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:release [
        doap:revision "0.1" ;
        doap:created "2011-04-02"
    ] ;
    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 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 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, 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>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 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>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: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>
""" .