aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/dynmanifest/dynmanifest.meta.ttl
blob: 7527494bf77b3e3c902a8333b7d36b6ef99b2e80 (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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
@prefix dcs: <http://ontologi.es/doap-changeset#> .
@prefix dman: <http://lv2plug.in/ns/ext/dynmanifest#> .
@prefix doap: <http://usefulinc.com/ns/doap#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

<http://lv2plug.in/ns/ext/dynmanifest>
	a doap:Project ;
	doap:license <http://opensource.org/licenses/isc> ;
	doap:name "LV2 Dynamic Manifest" ;
	doap:homepage <http://naspro.atheme.org> ;
	doap:created "2009-06-13" ;
	doap:shortdesc "Support for dynamic manifest data generation." ;
	doap:programming-language "C" ;
	doap:developer <http://lv2plug.in/ns/meta#daste> ;
	doap:release [
		doap:revision "1.6" ;
		doap:created "2012-10-14" ;
		doap:file-release <http://lv2plug.in/spec/lv2-1.2.0.tar.bz2> ;
		dcs:blame <http://drobilla.net/drobilla#me> ;
		dcs:changeset [
			dcs:item [
				rdfs:label "Use consistent label style."
			]
		]
	] , [
		doap:revision "1.4" ;
		doap:created "2012-04-17" ;
		doap:file-release <http://lv2plug.in/spec/lv2-1.0.0.tar.bz2> ;
		dcs:blame <http://drobilla.net/drobilla#me> ;
		dcs:changeset [
			dcs:item [
				rdfs:label "Merge with unified LV2 package."
			]
		]
	] , [
		doap:revision "1.2" ;
		doap:created "2011-11-21" ;
		doap:file-release <http://lv2plug.in/spec/lv2-dynmanifest-1.2.tar.bz2> ;
		dcs:blame <http://drobilla.net/drobilla#me> ;
		dcs:changeset [
			dcs:item [
				rdfs:label "Improve documentation."
			]
		]
	] , [
		doap:revision "1.0" ;
		doap:created "2010-04-10" ;
		doap:file-release <http://lv2plug.in/spec/lv2-dyn-manifest-1.0.tar.gz> ;
		dcs:blame <http://drobilla.net/drobilla#me> ;
		dcs:changeset [
			dcs:item [
				rdfs:label "Initial release."
			]
		]
	] ;
	lv2:documentation """

The LV2 API, on its own, cannot be used to write plugin libraries where data is
dynamically generated at runtime (e.g. API wrappers), since LV2 requires needed
information to be provided in one or more static data (RDF) files. This API
addresses this limitation by extending the LV2 API.

To detect that a plugin library implements a dynamic manifest generator, the
host checks its static manifest for a description like:

    :::turtle
    <http://example.org/my-dynamic-manifest>
        a dman:DynManifest ;
        lv2:binary <mydynmanifest.so> .

To load the data, the host loads the library (e.g. `mydynmanifest.so`) as usual
and fetches the dynamic Turtle data from it using this API.

The host is allowed to request regeneration of the dynamic manifest multiple
times, and the plugin library is expected to provide updated data if/when
possible. All data and references provided via this API before the last
regeneration of the dynamic manifest is to be considered invalid by the host,
including plugin descriptors whose URIs were discovered using this API.

### Accessing Data

To access data using this API, the host must:

  1. Call lv2_dyn_manifest_open().

  2. Create a `FILE` for functions to write data to (for example with `tmpfile()`).

  3. Get a list of exposed subject URIs using lv2_dyn_manifest_get_subjects().

  4. Call lv2_dyn_manifest_get_data() for each URI of interest to write the
  related data to the file.

  5. Call lv2_dyn_manifest_close().

  6. Parse the content of the file(s).

  7. Remove the file(s).

Each call to the above mentioned dynamic manifest functions MUST write a
complete, valid Turtle document (including all needed prefix definitions) to
the output FILE.

Each call to lv2_dyn_manifest_open() causes the (re)generation of the dynamic
manifest data, and invalidates all data fetched before the call.

In case the plugin library uses this same API to access other dynamic
manifests, it MUST implement some mechanism to avoid potentially endless loops
(such as A loads B, B loads A, etc.) and, in case such a loop is detected, the
operation MUST fail.  For this purpose, use of a static boolean flag is
suggested.

### Threading Rules

All of the functions defined by this specification belong to the Discovery
class.


"""^^lv2:Markdown .

dman:DynManifest
	lv2:documentation """

There MUST NOT be any instances of dman:DynManifest in the generated manifest.

All relative URIs in the generated data MUST be relative to the base path that
would be used to parse a normal LV2 manifest (the bundle path).

"""^^lv2:Markdown .