From 22a9dc0354eb1eb6b764b57d88561879c7731600 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Fri, 1 Apr 2011 18:43:28 +0000 Subject: Tidy. Fix copyright header (sloppy copy/paste artifact). Switch header to MIT license (same as data). --- ext/files.lv2/files.h | 82 ++++++++++++++++++++++++++++--------------------- ext/files.lv2/files.ttl | 46 +++++++++++++-------------- 2 files changed, 70 insertions(+), 58 deletions(-) diff --git a/ext/files.lv2/files.h b/ext/files.lv2/files.h index 4f0564f..4b93331 100644 --- a/ext/files.lv2/files.h +++ b/ext/files.lv2/files.h @@ -1,24 +1,29 @@ -/* lv2_files.h - C header file for the LV2 Files extension. - * Copyright (C) 2010 Leonard Ritter - * - * This header is free software; you can redistribute it and/or modify it - * under the terms of the GNU Lesser General Public License as published - * by the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This header is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public - * License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this header; if not, write to the Free Software Foundation, - * Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307 USA - */ - -/** @file - * C header for the LV2 Files extension . - */ +/* + Copyright 2010-2011 David Robillard + + 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. +*/ + +/** + @file files.h + C API for the LV2 Files extension . +*/ #ifndef LV2_FILES_H #define LV2_FILES_H @@ -31,24 +36,31 @@ extern "C" { typedef void* LV2_Files_FileSupport_Data; -/** Feature structure passed by host to instantiate with feature URI - * . - */ +/** + files:FileSupport feature struct. + + To support this feature, the host MUST pass an LV2_Feature struct with @a + URI "http://lv2plug.in/ns/ext/files#fileSupport" and @ data pointed to an + instance of this struct. +*/ typedef struct { + /** + Opaque host data. + */ LV2_Files_FileSupport_Data data; - /** Return the full path that should be used for a file owned by this - * plugin called @a name. The plugin can assume @a name belongs to a - * namespace dedicated to that plugin instance (i.e. hosts MUST ensure - * this, e.g. by giving each plugin its own directory for files, or - * mangling filenames somehow). - * - * @param data MUST be the @a data member of this struct. - * @param name The name of the file. - * @return A newly allocated path which the plugin may use to create a new - * file. The plugin is responsible for freeing the returned string. - */ + /** + Return the full path that should be used for a file owned by this + plugin called @a name. The plugin can assume @a name belongs to a + namespace dedicated to that plugin instance (i.e. hosts MUST ensure + this, e.g. by giving each plugin instance its own files directory). + + @param data MUST be the @a data member of this struct. + @param name The name of the file. + @return A newly allocated path which the plugin may use to create a new + file. The plugin is responsible for freeing the returned string. + */ char* new_file_path(LV2_Files_FileSupport_Data data, const char* name); diff --git a/ext/files.lv2/files.ttl b/ext/files.lv2/files.ttl index e3cf719..6b2b3ca 100644 --- a/ext/files.lv2/files.ttl +++ b/ext/files.lv2/files.ttl @@ -1,6 +1,5 @@ # LV2 Files Extension -# Copyright (C) 2010 Leonard Ritter -# Copyright (C) 2010 David Robillard +# Copyright 2010-2011 David Robillard # # Permission is hereby granted, free of charge, to any person obtaining a # copy of this software and associated documentation files (the "Software"), @@ -20,9 +19,9 @@ # ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR # OTHER DEALINGS IN THE SOFTWARE. -@prefix files: . -@prefix atom: . +@prefix atom: . @prefix doap: . +@prefix files: . @prefix foaf: . @prefix lv2: . @prefix rdf: . @@ -43,19 +42,20 @@ storing arbitrary data (e.g. waveforms), which can be persisted using the LV2 Persist extension. This allows plugins to work with potentially very large data via files, -and save/restore these files.

+and save/restore these files across plugin instances.

The motivating idea behind this extension is that all details of file -management must be handled by the host in whatever way is most appropriate for -that host. Plugins MUST NOT make any assumption about filesystem locations -beyond what is explicitly guaranteed by this extension.

+management MUST be handled by the host in whatever way is most appropriate for +that host, since hosts may have very different requirements. Plugins MUST NOT +make any assumption about filesystem locations beyond what is explicitly +guaranteed by this extension.

-

To create a new file, plugins request a filename from the host. This way, +

To create a new file, plugins request a filename from the host. This way, the host is aware of files used by the plugin and can use an appropriate location for them that the plugin alone could not know (e.g. using an appropriate disk volume for recording).

-

Plugins may also use pre-existing files from elsewhere on the filesystem. +

Plugins MAY also use pre-existing files from elsewhere on the filesystem. Using the LV2 Persist extension, the host can save both these types of files in an appropriate way (by e.g. storing a link, or copying the file to export or archive a project).

@@ -64,17 +64,17 @@ or archive a project).

files:fileSupport a lv2:Feature ; rdfs:label "Support for plugin-created files" ; lv2:documentation """ -

This feature allows plugins to use pre-existing or newly created files, -and files them (e.g. across project saves and restores). If a host supports -this feature it passes a LV2_Files_FileSupport structure to the plugins -instantiate method as a feature (with URI -http://lv2plug.in/ns/ext/files#FileSupport). This structure provides -a function the plugin can use to create new file names. If and only if the -host supports this feature, the plugin MAY files and restore values of -type LV2_FILES_FILENAME.

+ +

This feature allows plugins to use pre-existing or newly created files, and +persist them (e.g. across project saves and restores). If a host supports this +feature it passes a LV2_Files_FileSupport structure to the plugins instantiate +method as a feature (with URI http://lv2plug.in/ns/ext/files#FileSupport). This +structure provides a function the plugin can use to create new file names. If +and only if the host supports this feature, the plugin MAY files and restore +values of type LV2_FILES_FILENAME.

A plugin SHOULD use this facility to create any new files it may need -(e.g. samples, waveforms for recording). Plugins MUST NOT expect their +(e.g. samples, waveforms for recording). Plugins MUST NOT expect their state to be correctly restored if they do not use this mechanism to create new files.

""" . @@ -82,12 +82,12 @@ create new files.

files:FilePath a atom:AtomType ; rdfs:label "File Path" ; lv2:documentation """ -The full path to a file on the local filesystem. The format of a +The full path to a file on the local filesystem. The format of a files:filePath is a C string (escaped or otherwise restricted in whatever way -necessary for the system). This URI (http://lv2plug.in/ns/ext/files#FilePath), +necessary for the system). This URI (http://lv2plug.in/ns/ext/files#FilePath), mapped to an integer, should be used as the type parameter with -the LV2 Persist extension to persist a file. When persisting a files:FilePath, +the LV2 Persist extension to persist a file. When persisting a files:FilePath, the plugin MUST NOT assume that the same path will be restored (i.e. the -host MAY choose to store the file elsewhere). The plugin may, of course, +host MAY choose to store the file elsewhere). The plugin may, of course, assume that the actual contents of the file are equivalent when restored. """ . -- cgit v1.2.1