[Devel] [RFC] URID extension

[Gabriel Beddingfield]

In the uri-map extension, uri_to_id's second parameter ("map") is pretty awkward.  Defining URI=>ID mappings /per extension/ seems like overkill and is confusing to plugin implementers.

I'm proposing a `urid` extension, and would like your comments on it. It proposes a global registry of URI<==>ID mappings.  This registry maps the same URI's and ID's for all extensions and all plugins.

I've pasted the urid.h header below.  The full extension and a sample implementation may be found here:

   http://gabe.is-a-geek.org/tmp/urid.lv2-rfc-0.1.tar.bz2

Thanks,
Gabriel

/*
  Copyright 2011 Gabriel M. Beddingfield <gabrbedd at gmail.com>
  Copyright 2008-2011 David Robillard <http://drobilla.net>

  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.
*/

/**
   @file
   C header for the LV2 URID extension <http://example.tmp/rfc/urid>.

   This extension defines a simple mechanism for plugins to map URIs to
   integers, usually for performance reasons (e.g. processing events typed by
   URIs in real time). The expected use case is for plugins to map URIs to
   integers for things they 'understand' at instantiation time, and store those
   values for use in the audio thread without doing any string comparison.
   This allows the extensibility of RDF with the performance of integers (or
   centrally defined enumerations).
*/

#ifndef LV2_URID_H
#define LV2_URID_H

#define LV2_URID_URI "http://example.tmp/rfc/urid"

#include <stdint.h>

/**
   Opaque pointer to host data.
*/
typedef void* LV2_URID_Callback_Data;

/**
   URID Feature.

   To support this feature the host must pass an LV2_Feature struct to the
   plugin's instantiate method with URI "http://example.tmp/rfc/urid"
   and data pointed to an instance of this struct.
*/
typedef struct {

	/**
	   Opaque pointer to host data.
	
	   The plugin MUST pass this to any call to functions in this struct.
	   Otherwise, it must not be interpreted in any way.
	*/
	LV2_URID_Callback_Data callback_data;

	/**
	   Get the numeric ID of a URI from the host.
	
           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
	   fast or RT-safe: plugins SHOULD cache any IDs they might need in
           performance critical situations.
	
	   The return value 0 is reserved and indicates that an ID for that URI
	   could not be created for whatever reason. Extensions MAY define more
	   precisely what this means in a certain context, but in general plugins
	   SHOULD handle this situation as gracefully as possible. However, hosts
	   SHOULD NOT return 0 from this function in non-exceptional circumstances
	   (e.g. the URI map SHOULD be dynamic). Hosts that statically support only
	   a fixed set of URIs should not expect plugins to function correctly.
	*/
	uint32_t (*get_uri_id)(LV2_URID_Callback_Data callback_data,
                               const char*            uri);

	/**
	   Get the URI for a given numeric ID from the host.
	
	   @param callback_data Must be the callback_data member of this struct.
	   @param id The ID to be mapped back to the URI string.  Must be a valid,
           ASCII, URI.  If it is not, then the behavior is undefined.

           Returns 0 if the ID is not yet assigned.  If the ID has been assigned,
           then it returns the URI in a canonical form.  This may not be the exact
           same string that was originally passed to get_uri_id(), but it will be
           an identical string according to the URI spec.  A non-null return will
           always be the same for the life of the plugin.
	*/
        const char* (*get_uri)(LV2_URID_Callback_Data callback_data,
                               uint32_t               id);

} LV2_URID_Feature;

#endif /* LV2_URID_H */