From 434a3c065b0b9ac73692bc445b01e91123554e50 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sat, 5 Nov 2011 03:26:29 +0000 Subject: Separate features for mapping and unmapping. --- ext/urid.lv2/manifest.ttl | 2 +- ext/urid.lv2/urid.h | 66 ++++++++++++++++++++++++++++------------------- ext/urid.lv2/urid.ttl | 27 ++++++++++++------- 3 files changed, 58 insertions(+), 37 deletions(-) diff --git a/ext/urid.lv2/manifest.ttl b/ext/urid.lv2/manifest.ttl index 28b54e2..c77aff6 100644 --- a/ext/urid.lv2/manifest.ttl +++ b/ext/urid.lv2/manifest.ttl @@ -5,5 +5,5 @@ a lv2:Specification ; lv2:minorVersion 0 ; - lv2:microVersion 1 ; + lv2:microVersion 2 ; rdfs:seeAlso . diff --git a/ext/urid.lv2/urid.h b/ext/urid.lv2/urid.h index cc444b2..0a01aeb 100644 --- a/ext/urid.lv2/urid.h +++ b/ext/urid.lv2/urid.h @@ -28,9 +28,14 @@ #include /** - Opaque pointer to host data. + Opaque pointer to host data for LV2_URID_Mapper. */ -typedef void* LV2_URID_Callback_Data; +typedef void* LV2_URID_Mapper_Handle; + +/** + Opaque pointer to host data for LV2_URID_Unmapper. +*/ +typedef void* LV2_URID_Unmapper_Handle; /** URI mapped to an integer. @@ -38,30 +43,22 @@ typedef void* LV2_URID_Callback_Data; typedef uint32_t LV2_URID; /** - URID Feature. - - To support this feature the host must pass an LV2_Feature struct to the - plugin's instantiate method with URI "http://lv2plug.in/ns/ext/urid#URIMap" - and data pointed to an instance of this struct. + URI Mapper (http://lv2plug.in/ns/ext/urid#Mapper). */ typedef struct { - /** Opaque pointer to host data. - The plugin MUST pass this to any call to functions in this struct. + This MUST be passed to map_uri() whenever it is called. Otherwise, it must not be interpreted in any way. */ - LV2_URID_Callback_Data callback_data; + LV2_URID_Mapper_Handle handle; /** - Get the numeric ID of a URI from the host. + Get the numeric ID of a URI. If the ID does not already exist, it will be created. - @param callback_data Must be the callback_data member of this struct. - @param uri The URI to be mapped to an integer ID. - This function is referentially transparent; any number of calls with the same arguments is guaranteed to return the same value over the life of a plugin instance. However, this function is not necessarily very @@ -72,28 +69,43 @@ typedef struct { could not be created for whatever reason. However, hosts SHOULD NOT return 0 from this function in non-exceptional circumstances (i.e. the URI map SHOULD be dynamic). + + @param handle Must be the callback_data member of this struct. + @param uri The URI to be mapped to an integer ID. */ - LV2_URID (*map_uri)(LV2_URID_Callback_Data callback_data, + LV2_URID (*map_uri)(LV2_URID_Mapper_Handle handle, const char* uri); +} LV2_URID_Mapper; +/** + URI Unmapper (http://lv2plug.in/ns/ext/urid#Unmapper). +*/ +typedef struct { /** - Get the URI for a given numeric ID from the host. + Opaque pointer to host data. - @param callback_data Must be the callback_data member of this struct. - @param id The ID to be mapped back to the URI string. + This MUST be passed to unmap_uri() whenever it is called. + Otherwise, it must not be interpreted in any way. + */ + LV2_URID_Unmapper_Handle handle; - Returns NULL if @c id is not yet mapped. Otherwise, the corresponding - URI is returned in a canonical form. This may not be the exact same - string that was originally passed to map_uri(), but it will be an + /** + Get the URI for a previously mapped numeric ID. + + Returns NULL if @c urid is not yet mapped. Otherwise, the corresponding + URI is returned in a canonical form. This MAY not be the exact same + string that was originally passed to map_uri(), but it MUST be an identical URI according to the URI spec. A non-NULL return for a given - @c id will always be the same for the life of the plugin. Plugins that - intend to perform string comparison on unmapped URIs should first + @c urid will always be the same for the life of the plugin. Plugins + that intend to perform string comparison on unmapped URIs SHOULD first canonicalise URI strings with a call to map_uri() followed by a call to unmap_uri(). - */ - const char* (*unmap_uri)(LV2_URID_Callback_Data callback_data, - LV2_URID urid); -} LV2_URID_Feature; + @param handle Must be the callback_data member of this struct. + @param urid The ID to be mapped back to the URI string. + */ + const char* (*unmap_uri)(LV2_URID_Unmapper_Handle handle, + LV2_URID urid); +} LV2_URID_Unmapper; #endif /* LV2_URID_H */ diff --git a/ext/urid.lv2/urid.ttl b/ext/urid.lv2/urid.ttl index fdc4871..94b6863 100644 --- a/ext/urid.lv2/urid.ttl +++ b/ext/urid.lv2/urid.ttl @@ -26,10 +26,10 @@ doap:name "LV2 URID" ; doap:shortdesc "Features for mapping URIs to and from integers." ; doap:release [ - doap:revision "0.1" ; - doap:created "2011-07-20" + doap:revision "0.2" ; + doap:created "2011-01-04" ] ; - doap:maintainer [ + doap:developer [ a foaf:Person ; foaf:name "Gabriel M. Beddingfield" ; foaf:homepage @@ -47,12 +47,21 @@ This extension is intended as an improved and simpler replacement for the map context parameter has been found problematic. """ . -urid:URIMap +urid:Mapper a lv2:Feature ; lv2:documentation """ -An lv2:Feature which provides URI mapping and unmapping capability. To support -this feature, the host must pass an LV2_Feature to -LV2_Descriptor::instantiate with URI -http://lv2plug.in/ns/ext/urid#URIMap and data pointed to an instance of -LV2_URID_Feature. +A feature which is used to map URIs to integers. To support this feature, the +host must pass an LV2_Feature to LV2_Descriptor::instantiate() with +URI http://lv2plug.in/ns/ext/urid#Mapper and data +pointed to an instance of LV2_URID_Mapper. +""" . + +urid:Unmapper + a lv2:Feature ; + lv2:documentation """ +A feature which is used to unmap URIs previously mapped to integers by Mapper. To support this feature, the host must pass an +LV2_Feature to LV2_Descriptor::instantiate() with URI +http://lv2plug.in/ns/ext/urid#Unmapper and data pointed to an +instance of LV2_URID_Unmapper. """ . -- cgit v1.2.1