# LV2 Files Extension # Copyright 2010-2011 David Robillard # # 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: . @prefix doap: . @prefix files: . @prefix foaf: . @prefix lv2: . @prefix rdf: . @prefix rdfs: . @prefix xsd: . a lv2:Specification ; doap:name "LV2 Files" ; doap:shortdesc "A standard for referring to files in plugin state." ; doap:license ; doap:release [ doap:revision "0.2" ; doap:created "2011-04-05" ] ; doap:maintainer [ a foaf:Person ; foaf:name "David Robillard" ; foaf:homepage ; rdfs:seeAlso ] ; lv2:documentation """

This extension provides a mechanism for plugins to portably refer to files in persistent plugin state (using the LV2 Persist extension), and create instance-local files in host-defined locations (e.g. for recording).

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.

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.

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.

To store a path in persistent state, the plugin MUST map it to an abstract path 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.

""" . files:pathSupport a lv2:Feature ; rdfs:label "Support for storing file paths in plugin state" ; lv2:documentation """

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.

Plugins MUST use the functions provided by this feature to handle all 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.

""" . files:newFileSupport a lv2:Feature ; rdfs:label "Support for creating new files" ; lv2:documentation """

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.

""" . files:AbstractPath a rdfs:class ; rdfs:label "File Path" ; lv2:documentation """

An abstract path to a file in persistent plugin state.

The format of a files:AbstractPath is a C string escaped or otherwise restricted in a system-specific manner. This URI, http://lv2plug.in/ns/ext/files#AbstractPath, mapped to an integer, should be used as the type parameter to a LV2_Persist_Store_Function; and will likewise be returned by the corresponding call to a LV2_Persist_Retrieve_Function.

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.

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.

""" .