Description

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:

<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

Whenever a host wants to access data using this API, it could:

  1. Call lv2_dyn_manifest_open().
  2. Create a FILE for functions to write data to (e.g. using 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 get the data related to that URI (which can be written to any FILE).
  5. Call lv2_dyn_manifest_close().
  6. Parse the content of the FILE(s).
  7. Free/delete/unlink 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.

Index

Classes

Reference

Class dman:DynManifest

Dynamic Manifest

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

Restriction on lv2:binary
owl:minCardinality 1
A DynManifest MUST have at least 1 lv2:binary, which MUST implement all the functions defined in dynmanifest.h.

History

Version 2.0 (2014-08-08)
  • Add lv2_atom_forge_is_object_type() and lv2_atom_forge_is_blank() to ease backwards compatibility.
  • Deprecate Blank and Resource in favour of just Object.
  • Add lv2_atom_forge_key() for terser object writing.
  • Add lv2_atom_sequence_clear() and lv2_atom_sequence_append_event() helper functions.
Version 1.8 (2014-01-04)
  • Make lv2_atom_*_is_end() arguments const.
Version 1.6 (2013-05-26)
  • Fix crash in forge.h when pushing atoms to a full buffer.
Version 1.4 (2013-01-27)
  • Fix lv2_atom_sequence_end().
  • Remove atom:stringType in favour of owl:onDatatype so generic tools can understand and validate atom literals.
  • Improve atom documentation.
Version 1.2 (2012-12-21)
  • Fix typo in bufsz:sequenceSize label.
Version 1.0 (2012-10-14)
  • Initial release.
Version 1.6 (2012-04-17)
  • Merge with unified LV2 package.
Version 1.4 (2011-11-21)
  • Improve documentation.
  • Update packaging.
Version 1.2 (2011-05-26)
  • Switch to ISC license.
  • Add build system for installation.
Version 1.0 (2010-10-04)
  • Initial release.