From 9977d659105937112587e7eb68c59fae7169d945 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sat, 18 Feb 2012 23:12:49 +0000 Subject: Remove state:Path and use new atom:Path instead. Remove suggestion to use file URIs in plugins, which is much too tedious. If plugins use standard atom types, hosts should be able to map paths in any way (which they may need to regardless). Unfortunately it's slightly less pretty in Turtle to have a special path type rather than a (possibly relative) URI. Factor out common write_set_filename_msg in sampler example. Establish common URI define convention LV2_EXTNAME__URILOCALNAME and define all URIs in state, message, and atom. --- lv2/lv2plug.in/ns/ext/atom/atom-test.c | 37 ++++++++++++++++++++++++--------- lv2/lv2plug.in/ns/ext/atom/atom.h | 31 +++++++++++++++++++++++++++ lv2/lv2plug.in/ns/ext/atom/atom.ttl | 26 ++++++++++++++--------- lv2/lv2plug.in/ns/ext/atom/forge.h | 32 ++++++++++++++++++++++------ lv2/lv2plug.in/ns/ext/message/message.h | 31 +++++++++++++-------------- lv2/lv2plug.in/ns/ext/state/state.h | 11 +++++----- lv2/lv2plug.in/ns/ext/state/state.ttl | 23 +++----------------- 7 files changed, 124 insertions(+), 67 deletions(-) (limited to 'lv2/lv2plug.in/ns/ext') diff --git a/lv2/lv2plug.in/ns/ext/atom/atom-test.c b/lv2/lv2plug.in/ns/ext/atom/atom-test.c index 2cc0da9..2011f68 100644 --- a/lv2/lv2plug.in/ns/ext/atom/atom-test.c +++ b/lv2/lv2plug.in/ns/ext/atom/atom-test.c @@ -72,16 +72,17 @@ main() LV2_URID eg_four = urid_map(NULL, "http://example.org/four"); LV2_URID eg_true = urid_map(NULL, "http://example.org/true"); LV2_URID eg_false = urid_map(NULL, "http://example.org/false"); + LV2_URID eg_path = urid_map(NULL, "http://example.org/path"); LV2_URID eg_uri = urid_map(NULL, "http://example.org/uri"); LV2_URID eg_urid = urid_map(NULL, "http://example.org/urid"); LV2_URID eg_string = urid_map(NULL, "http://example.org/string"); LV2_URID eg_literal = urid_map(NULL, "http://example.org/literal"); LV2_URID eg_tuple = urid_map(NULL, "http://example.org/tuple"); LV2_URID eg_vector = urid_map(NULL, "http://example.org/vector"); - LV2_URID eg_seq = urid_map(NULL, "http://example.org/seq"); + LV2_URID eg_seq = urid_map(NULL, "http: //example.org/seq"); #define BUF_SIZE 1024 -#define NUM_PROPS 13 +#define NUM_PROPS 14 uint8_t buf[BUF_SIZE]; lv2_atom_forge_set_buffer(&forge, buf, BUF_SIZE); @@ -132,15 +133,26 @@ main() return test_fail("%ld != 0 (false)\n", f->value); } + // eg_path = (Path)"/foo/bar" + const uint8_t* pstr = (const uint8_t*)"/foo/bar"; + const size_t pstr_len = strlen((const char*)pstr); + lv2_atom_forge_property_head(&forge, eg_path, 0); + LV2_Atom_String* path = lv2_atom_forge_uri(&forge, pstr, pstr_len); + uint8_t* pbody = (uint8_t*)LV2_ATOM_BODY(path); + if (strcmp((const char*)pbody, (const char*)pstr)) { + return test_fail("%s != \"%s\"\n", + (const char*)pbody, (const char*)pstr); + } + // eg_uri = (URI)"http://example.org/value" const uint8_t* ustr = (const uint8_t*)"http://example.org/value"; const size_t ustr_len = strlen((const char*)ustr); lv2_atom_forge_property_head(&forge, eg_uri, 0); - LV2_Atom_String* uri = lv2_atom_forge_uri(&forge, ustr, ustr_len); - uint8_t* body = (uint8_t*)LV2_ATOM_BODY(uri); - if (strcmp((const char*)body, (const char*)ustr)) { + LV2_Atom_String* uri = lv2_atom_forge_uri(&forge, ustr, ustr_len); + uint8_t* ubody = (uint8_t*)LV2_ATOM_BODY(uri); + if (strcmp((const char*)ubody, (const char*)ustr)) { return test_fail("%s != \"%s\"\n", - (const char*)body, (const char*)ustr); + (const char*)ubody, (const char*)ustr); } // eg_urid = (URID)"http://example.org/value" @@ -157,7 +169,7 @@ main() &forge, (const uint8_t*)"hello", strlen("hello")); uint8_t* sbody = (uint8_t*)LV2_ATOM_BODY(string); if (strcmp((const char*)sbody, "hello")) { - return test_fail("%s != \"hello\"\n", (const char*)body); + return test_fail("%s != \"hello\"\n", (const char*)sbody); } // eg_literal = (Literal)"hello"@fr @@ -165,9 +177,9 @@ main() LV2_Atom_Literal* literal = lv2_atom_forge_literal( &forge, (const uint8_t*)"bonjour", strlen("bonjour"), 0, urid_map(NULL, "http://lexvo.org/id/term/fr")); - body = (uint8_t*)LV2_ATOM_CONTENTS(LV2_Atom_Literal, literal); - if (strcmp((const char*)body, "bonjour")) { - return test_fail("%s != \"bonjour\"\n", (const char*)body); + uint8_t* lbody = (uint8_t*)LV2_ATOM_CONTENTS(LV2_Atom_Literal, literal); + if (strcmp((const char*)lbody, "bonjour")) { + return test_fail("%s != \"bonjour\"\n", (const char*)lbody); } // eg_tuple = "foo",true @@ -267,6 +279,7 @@ main() const LV2_Atom* four; const LV2_Atom* affirmative; const LV2_Atom* negative; + const LV2_Atom* path; const LV2_Atom* uri; const LV2_Atom* urid; const LV2_Atom* string; @@ -285,6 +298,7 @@ main() { eg_four, &matches.four }, { eg_true, &matches.affirmative }, { eg_false, &matches.negative }, + { eg_path, &matches.path }, { eg_uri, &matches.uri }, { eg_urid, &matches.urid }, { eg_string, &matches.string }, @@ -312,6 +326,8 @@ main() return test_fail("Bad match true\n"); } else if (!lv2_atom_equals((LV2_Atom*)f, matches.negative)) { return test_fail("Bad match false\n"); + } else if (!lv2_atom_equals((LV2_Atom*)path, matches.path)) { + return test_fail("Bad match path\n"); } else if (!lv2_atom_equals((LV2_Atom*)uri, matches.uri)) { return test_fail("Bad match URI\n"); } else if (!lv2_atom_equals((LV2_Atom*)string, matches.string)) { @@ -333,6 +349,7 @@ main() eg_four, &matches.four, eg_true, &matches.affirmative, eg_false, &matches.negative, + eg_path, &matches.path, eg_uri, &matches.uri, eg_urid, &matches.urid, eg_string, &matches.string, diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.h b/lv2/lv2plug.in/ns/ext/atom/atom.h index 66f0490..f45ba74 100644 --- a/lv2/lv2plug.in/ns/ext/atom/atom.h +++ b/lv2/lv2plug.in/ns/ext/atom/atom.h @@ -27,6 +27,37 @@ #define LV2_ATOM_URI "http://lv2plug.in/ns/ext/atom" +#define LV2_ATOM__Atom LV2_ATOM_URI "#Atom" +#define LV2_ATOM__Bang LV2_ATOM_URI "#Bang" +#define LV2_ATOM__Number LV2_ATOM_URI "#Number" +#define LV2_ATOM__Int32 LV2_ATOM_URI "#Int32" +#define LV2_ATOM__Int64 LV2_ATOM_URI "#Int64" +#define LV2_ATOM__Float LV2_ATOM_URI "#Float" +#define LV2_ATOM__Double LV2_ATOM_URI "#Double" +#define LV2_ATOM__Bool LV2_ATOM_URI "#Bool" +#define LV2_ATOM__String LV2_ATOM_URI "#String" +#define LV2_ATOM__Literal LV2_ATOM_URI "#Literal" +#define LV2_ATOM__Path LV2_ATOM_URI "#Path" +#define LV2_ATOM__URI LV2_ATOM_URI "#URI" +#define LV2_ATOM__URID LV2_ATOM_URI "#URID" +#define LV2_ATOM__Vector LV2_ATOM_URI "#Vector" +#define LV2_ATOM__Tuple LV2_ATOM_URI "#Tuple" +#define LV2_ATOM__Property LV2_ATOM_URI "#Property" +#define LV2_ATOM__Object LV2_ATOM_URI "#Object" +#define LV2_ATOM__Resource LV2_ATOM_URI "#Resource" +#define LV2_ATOM__Blank LV2_ATOM_URI "#Blank" +#define LV2_ATOM__TimeUnit LV2_ATOM_URI "#TimeUnit" +#define LV2_ATOM__AudioFrames LV2_ATOM_URI "#AudioFrames" +#define LV2_ATOM__Beats LV2_ATOM_URI "#Beats" +#define LV2_ATOM__Event LV2_ATOM_URI "#Event" +#define LV2_ATOM__Sequence LV2_ATOM_URI "#Sequence" +#define LV2_ATOM__AtomPort LV2_ATOM_URI "#AtomPort" +#define LV2_ATOM__ValuePort LV2_ATOM_URI "#ValuePort" +#define LV2_ATOM__MessagePort LV2_ATOM_URI "#MessagePort" +#define LV2_ATOM__bufferType LV2_ATOM_URI "#bufferType" +#define LV2_ATOM__supports LV2_ATOM_URI "#supports" +#define LV2_ATOM__eventTransfer LV2_ATOM_URI "#eventTransfer" + #define LV2_ATOM_REFERENCE_TYPE 0 #include diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.ttl b/lv2/lv2plug.in/ns/ext/atom/atom.ttl index 70a1252..677a159 100644 --- a/lv2/lv2plug.in/ns/ext/atom/atom.ttl +++ b/lv2/lv2plug.in/ns/ext/atom/atom.ttl @@ -218,22 +218,28 @@ void set_to_turtle_string(LV2_Atom_Literal* lit, const char* ttl) { """ . +atom:Path + a rdfs:Class ; + rdfs:subClassOf atom:String ; + rdfs:label "File path string" ; + lv2:documentation """ +

A local file path string. This is identical in format to atom:String, +except the string is a path. Since the ability to distinguish paths from plain +strings is often necessary, paths MUST NOT be transmitted as atom:String.

+""" . + atom:URI a rdfs:Class ; rdfs:subClassOf atom:String ; rdfs:label "URI string" ; lv2:documentation """

A URI string. This is identical in format to atom:String, except the string -is a URI. This is occasionally useful when a URI is needed but mapping it is -inappropriate. URIs should never be expressed as atom:String, because this -makes it impossible to distinguish URIs from arbitrary strings, which makes -functionality like mapping or rewriting URIs impossible. Similarly, there is -deliberately no atom type for filesystem paths. To refer to a filename, use a -complete file URI, with hostname if at all possible. This allows hosts to -properly handle paths in situations like serialisation or network -transmission.

- -

Pedantically, this is an IRI, since UTF-8 characters are allowed.

+is a URI. This is useful when a URI is needed but mapping is inappropriate. +Since the ability to distinguish URIs from plain strings is often necessary, +URIs MUST NOT be transmitted as atom:String.

+ +

This is not strictly a URI, since UTF-8 is allowed. Escaping and related +issues issues are the host's responsibility.

""" . atom:URID diff --git a/lv2/lv2plug.in/ns/ext/atom/forge.h b/lv2/lv2plug.in/ns/ext/atom/forge.h index 4db9638..06f24f5 100644 --- a/lv2/lv2plug.in/ns/ext/atom/forge.h +++ b/lv2/lv2plug.in/ns/ext/atom/forge.h @@ -85,6 +85,7 @@ typedef struct { LV2_URID Int32; LV2_URID Int64; LV2_URID Literal; + LV2_URID Path; LV2_URID Property; LV2_URID Resource; LV2_URID Sequence; @@ -172,6 +173,7 @@ lv2_atom_forge_init(LV2_Atom_Forge* forge, LV2_URID_Map* map) forge->Int32 = map->map(map->handle, LV2_ATOM_URI "#Int32"); forge->Int64 = map->map(map->handle, LV2_ATOM_URI "#Int64"); forge->Literal = map->map(map->handle, LV2_ATOM_URI "#Literal"); + forge->Path = map->map(map->handle, LV2_ATOM_URI "#Path"); forge->Property = map->map(map->handle, LV2_ATOM_URI "#Property"); forge->Resource = map->map(map->handle, LV2_ATOM_URI "#Resource"); forge->Sequence = map->map(map->handle, LV2_ATOM_URI "#Sequence"); @@ -322,13 +324,31 @@ lv2_atom_forge_uri(LV2_Atom_Forge* forge, const LV2_Atom_String a = { { forge->URI, len + 1 } }; LV2_Atom_String* out = (LV2_Atom_String*) lv2_atom_forge_write_nopad(forge, &a, sizeof(a)); - if (!out) { - return NULL; + if (out) { + if (!lv2_atom_forge_string_body(forge, uri, len)) { + out->atom.type = 0; + out->atom.size = 0; + out = NULL; + } } - if (!lv2_atom_forge_string_body(forge, uri, len)) { - out->atom.type = 0; - out->atom.size = 0; - return NULL; + return out; +} + +/** Write an atom:Path. Note that @p path need not be NULL terminated. */ +static inline LV2_Atom_String* +lv2_atom_forge_path(LV2_Atom_Forge* forge, + const uint8_t* path, + size_t len) +{ + const LV2_Atom_String a = { { forge->Path, len + 1 } }; + LV2_Atom_String* out = (LV2_Atom_String*) + lv2_atom_forge_write_nopad(forge, &a, sizeof(a)); + if (out) { + if (!lv2_atom_forge_string_body(forge, path, len)) { + out->atom.type = 0; + out->atom.size = 0; + out = NULL; + } } return out; } diff --git a/lv2/lv2plug.in/ns/ext/message/message.h b/lv2/lv2plug.in/ns/ext/message/message.h index 9c03713..728b836 100644 --- a/lv2/lv2plug.in/ns/ext/message/message.h +++ b/lv2/lv2plug.in/ns/ext/message/message.h @@ -27,21 +27,20 @@ #define LV2_MESSAGE_URI "http://lv2plug.in/ns/ext/message" -#define LV2_MESSAGE_Ack LV2_MESSAGE_URI "#Ack" -#define LV2_MESSAGE_Delete LV2_MESSAGE_URI "#Delete" -#define LV2_MESSAGE_Error LV2_MESSAGE_URI "#Error" -#define LV2_MESSAGE_Get LV2_MESSAGE_URI "#Get" -#define LV2_MESSAGE_Message LV2_MESSAGE_URI "#Message" -#define LV2_MESSAGE_Move LV2_MESSAGE_URI "#Move" -#define LV2_MESSAGE_Patch LV2_MESSAGE_URI "#Patch" -#define LV2_MESSAGE_Post LV2_MESSAGE_URI "#Post" -#define LV2_MESSAGE_Put LV2_MESSAGE_URI "#Put" -#define LV2_MESSAGE_Request LV2_MESSAGE_URI "#Request" -#define LV2_MESSAGE_Response LV2_MESSAGE_URI "#Response" -#define LV2_MESSAGE_Set LV2_MESSAGE_URI "#Set" - -#define LV2_MESSAGE_add LV2_MESSAGE_URI "#add" -#define LV2_MESSAGE_body LV2_MESSAGE_URI "#body" -#define LV2_MESSAGE_cause LV2_MESSAGE_URI "#cause" +#define LV2_MESSAGE__Ack LV2_MESSAGE_URI "#Ack" +#define LV2_MESSAGE__Delete LV2_MESSAGE_URI "#Delete" +#define LV2_MESSAGE__Error LV2_MESSAGE_URI "#Error" +#define LV2_MESSAGE__Get LV2_MESSAGE_URI "#Get" +#define LV2_MESSAGE__Message LV2_MESSAGE_URI "#Message" +#define LV2_MESSAGE__Move LV2_MESSAGE_URI "#Move" +#define LV2_MESSAGE__Patch LV2_MESSAGE_URI "#Patch" +#define LV2_MESSAGE__Post LV2_MESSAGE_URI "#Post" +#define LV2_MESSAGE__Put LV2_MESSAGE_URI "#Put" +#define LV2_MESSAGE__Request LV2_MESSAGE_URI "#Request" +#define LV2_MESSAGE__Response LV2_MESSAGE_URI "#Response" +#define LV2_MESSAGE__Set LV2_MESSAGE_URI "#Set" +#define LV2_MESSAGE__add LV2_MESSAGE_URI "#add" +#define LV2_MESSAGE__body LV2_MESSAGE_URI "#body" +#define LV2_MESSAGE__cause LV2_MESSAGE_URI "#cause" #endif /* LV2_MESSAGE_H */ diff --git a/lv2/lv2plug.in/ns/ext/state/state.h b/lv2/lv2plug.in/ns/ext/state/state.h index b450b93..aa272b7 100644 --- a/lv2/lv2plug.in/ns/ext/state/state.h +++ b/lv2/lv2plug.in/ns/ext/state/state.h @@ -36,10 +36,11 @@ extern "C" { #define LV2_STATE_URI "http://lv2plug.in/ns/ext/state" -#define LV2_STATE_INTERFACE_URI LV2_STATE_URI "#Interface" -#define LV2_STATE_PATH_URI LV2_STATE_URI "#Path" -#define LV2_STATE_MAP_PATH_URI LV2_STATE_URI "#mapPath" -#define LV2_STATE_MAKE_PATH_URI LV2_STATE_URI "#makePath" +#define LV2_STATE__Interface LV2_STATE_URI "#Interface" +#define LV2_STATE__State LV2_STATE_URI "#State" +#define LV2_STATE__state LV2_STATE_URI "#state" +#define LV2_STATE__mapPath LV2_STATE_URI "#mapPath" +#define LV2_STATE__makePath LV2_STATE_URI "#makePath" typedef void* LV2_State_Handle; typedef void* LV2_State_Map_Path_Handle; @@ -315,7 +316,7 @@ typedef struct { } LV2_State_Map_Path; /** - Feature data for state:makePath (@ref LV2_STATE_MAKE_PATH_URI). + Feature data for state:makePath (@ref LV2_STATE__makePath). */ typedef struct { diff --git a/lv2/lv2plug.in/ns/ext/state/state.ttl b/lv2/lv2plug.in/ns/ext/state/state.ttl index 6c0656a..4b86eb6 100644 --- a/lv2/lv2plug.in/ns/ext/state/state.ttl +++ b/lv2/lv2plug.in/ns/ext/state/state.ttl @@ -193,7 +193,9 @@ Map get_plugin_state(LV2_Handle instance)

Plugins may need to refer to files (e.g. loaded samples) in their state. This is done by storing the file's path as a property just like any other value. However, there are some rules which MUST be followed when storing -paths, see state:mapPath for details.

+paths, see state:mapPath for details. Plugins MUST +use the type atom:Path +for all paths in their state.

Creating New Files or Directories

@@ -267,7 +269,6 @@ state:mapPath a lv2:Feature ; rdfs:label "Support for storing paths in files" ; lv2:documentation """ -

This feature maps absolute paths to/from abstract paths which are stored in state. To support this feature a host must pass an LV2_Feature with URI LV2_STATE_MAP_PATH_URI and data pointed to an LV2_State_Map_Path to the @@ -305,7 +306,6 @@ state:makePath a lv2:Feature ; rdfs:label "Support for creating new files and directories" ; lv2:documentation """ -

This feature allows plugins to create new files and/or directories. To support this feature the host passes an LV2_Feature with URI LV2_STATE_MAKE_PATH_URI and data pointed to an LV2_State_Make_Path to the @@ -340,20 +340,3 @@ char* save_myfile(LV2_State_Make_Path* make_path) } """ . - -state:Path - a rdfs:Class ; - rdfs:label "Path" ; - lv2:documentation """ -

A path to a file or directory.

- -

The format of a state:Path is a C string, possibly escaped or otherwise -restricted in a system-specific manner. This URI (LV2_STATE_PATH_URI), mapped -to an integer, MUST be used as the type parameter for any files -passed to the LV2_State_Store_Function; and will likewise be returned by the -corresponding call to the LV2_State_Retrieve_Function.

- -

When storing and retrieving a 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.

-""" . -- cgit v1.2.1