# LV2 Dynamic Manifest Extension
# Copyright 2008-2011 Stefano D'Angelo <zanga.mail@gmail.com>
#
# 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 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 owl:  <http://www.w3.org/2002/07/owl#> .
@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/dynmanifest>
	a lv2:Specification ;
    lv2:documentation """
<p>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.</p>

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

<pre class="turtle-code">
&lt;http://example.org/my-dynamic-manifest&gt;
    a dman:DynManifest ;
    lv2:binary &lt;mydynmanifest.so&gt; .
</pre>

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

<p>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.</p>

<h3>Accessing Data</h3>

<p>Whenever a host wants to access data using this API, it could:</p>

<ol>
<li>Call lv2_dyn_manifest_open().</li>
<li>Create a FILE for functions to write data to (e.g. using tmpfile()).</li>
<li>Get a <q>list</q> of exposed subject URIs using
    lv2_dyn_manifest_get_subjects().</li>
<li>Call lv2_dyn_manifest_get_data() for each URI of interest to
    get the data related to that URI (which can be written to any FILE).</li>
<li>Call lv2_dyn_manifest_close().</li>
<li>Parse the content of the FILE(s).</li>
<li>Free/delete/unlink the FILE(s).</li>
</ol>

<p>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.</p>

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

<p>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.</p>

<h3>Threading Rules</h3>

<p>All of the functions defined by this specification belong to the Discovery
class.</p>
""" .

dman:DynManifest
	a rdfs:Class ;
	rdfs:subClassOf lv2:Resource ;
	rdfs:label "Dynamic manifest generator" ;
	rdfs:subClassOf [
		a owl:Restriction ;
		owl:onProperty lv2:binary ;
		owl:minCardinality 1 ;
		rdfs:comment """
A DynManifest MUST have at least 1 lv2:binary, which MUST implement all the
functions defined in dynmanifest.h.
"""
	] ;
	rdfs:comment """
The class which represents a dynamic manifest generator.

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).
""" .