Moved libslv2 into it's own subdirectory

git-svn-id: http://svn.drobilla.net/lad/libslv2@4 a436a847-0d15-0410-975c-d299462d15a1

9 files changed, 928 insertions, 0 deletions

diff --git a/slv2/Makefile.am b/slv2/Makefile.am
new file mode 100644
index 0000000..fafe21d
--- /dev/null
+++ b/slv2/Makefile.am
@@ -0,0 +1,11 @@
+slv2includedir = $(includedir)/slv2
+
+slv2include_HEADERS = \
+	types.h \
+	private_types.h \
+	slv2.h \
+	plugin.h \
+	query.h \
+	port.h \
+	pluginlist.h \
+	plugininstance.h
diff --git a/slv2/plugin.h b/slv2/plugin.h
new file mode 100644
index 0000000..6af04bc
--- /dev/null
+++ b/slv2/plugin.h
@@ -0,0 +1,168 @@
+/* LibSLV2
+ * Copyright (C) 2006 Dave Robillard <drobilla@connect.carleton.ca>
+ *  
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This library 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 General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifndef __SLV2_PLUGIN_H__
+#define __SLV2_PLUGIN_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+	
+#include <stddef.h>
+#include <stdbool.h>
+#include "types.h"
+
+
+typedef const struct _Plugin SLV2Plugin;
+
+
+/** \defgroup data Plugin data file access
+ *
+ * These functions work exclusively with the plugin's RDF data file.  They do
+ * not load the plugin dynamic library (or access
+ * it in any way).
+ *
+ * @{
+ */
+
+
+/** Check if this plugin is valid.
+ *
+ * This is used by plugin lists to avoid loading plugins that are not valid
+ * and will not work with libslv2 (eg plugins missing required fields, or
+ * having multiple values for mandatory single-valued fields, etc.
+ * 
+ * Note that normal hosts do not need to worry about list - libslv2 does not
+ * load invalid plugins in to plugin lists.  This is included for plugin
+ * testing utilities, etc.
+ *
+ * \return True if \a plugin is valid.
+ */
+bool
+slv2_plugin_verify(const SLV2Plugin* plugin);
+
+
+/** Duplicate a plugin.
+ *
+ * Use this if you want to keep an SLV2Plugin around but free the list it came
+ * from.
+ *
+ * \return a newly allocated SLV2Plugin identical to \a plugin (a deep copy).
+ */
+SLV2Plugin*
+slv2_plugin_duplicate(const SLV2Plugin* plugin);
+
+
+/** Get the URI of \a plugin.
+ *
+ * Any serialization that refers to plugins should refer to them by this.
+ * Hosts SHOULD NOT save any filesystem paths, plugin indexes, etc. in saved
+ * files; save only the URI.
+ *
+ * The URI is a globally unique identifier for one specific plugin.  Two
+ * plugins with the same URI are compatible in port signature, and should
+ * be guaranteed to work in a compatible and consistent way.  If a plugin
+ * is upgraded in an incompatible way (eg if it has different ports), it
+ * MUST have a different URI than it's predecessor.
+ *
+ * \return a shared string which must not be modified or free()'d.
+ */
+const unsigned char*
+slv2_plugin_get_uri(const SLV2Plugin* plugin);
+
+
+/** Get the URL of the RDF data file plugin information is located in.
+ *
+ * Only file: URL's are supported at this time.
+ *
+ * \return a complete URL eg. "file:///usr/foo/SomeBundle.lv2/someplug.ttl",
+ * which is shared and must not be modified or free()'d.
+ */
+const unsigned char*
+slv2_plugin_get_data_url(const SLV2Plugin* plugin);
+
+
+/** Get the local filesystem path of the RDF data file for \a plugin.
+ *
+ * \return a valid path on the local filesystem
+ * eg. "/usr/foo/SomeBundle.lv2/someplug.ttl" which is shared and must not
+ * be free()'d; or NULL if URL is not a local filesystem path.
+ */
+const unsigned char*
+slv2_plugin_get_data_path(const SLV2Plugin* plugin);
+
+
+/** Get the URL of the shared library for \a plugin.
+ *
+ * \return a shared string which must not be modified or free()'d.
+ */
+const unsigned char*
+slv2_plugin_get_library_url(const SLV2Plugin* plugin);
+
+
+/** Get the local filesystem path of the shared library for \a plugin.
+ *
+ * \return a valid path on the local filesystem
+ * eg. "/usr/foo/SomeBundle.lv2/someplug.so" which is shared and must not
+ * be free()'d; or NULL if URL is not a local filesystem path.
+ */
+const unsigned char*
+slv2_plugin_get_library_path(const SLV2Plugin* plugin);
+
+
+/** Get the name of \a plugin.
+ *
+ * This is guaranteed to return the untranslated name (the doap:name in the
+ * data file without a language tag).  Returned value must be free()'d by
+ * the caller.
+ */
+unsigned char*
+slv2_plugin_get_name(const SLV2Plugin* plugin);
+
+
+/** Request some property of the plugin.
+ *
+ * May return NULL if the property was not found (ie is not defined in the
+ * data file).
+ *
+ * Return value must be free()'d by caller.
+ *
+ * Note that some properties may have multiple values. If the property is a
+ * string with multiple languages defined, the translation according to
+ * $LANG will be returned if it is set.  Otherwise all values will be
+ * returned.
+ */
+SLV2Property
+slv2_plugin_get_property(const SLV2Plugin* p,
+                         const char*       property);
+
+
+/** Get the number of ports on this plugin.
+ */
+unsigned long
+slv2_plugin_get_num_ports(const SLV2Plugin* p);
+
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __SLV2_PLUGIN_H__ */
+
diff --git a/slv2/plugininstance.h b/slv2/plugininstance.h
new file mode 100644
index 0000000..5fd9393
--- /dev/null
+++ b/slv2/plugininstance.h
@@ -0,0 +1,205 @@
+/* LibSLV2
+ * Copyright (C) 2006 Dave Robillard <drobilla@connect.carleton.ca>
+ *  
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This library 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 General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifndef __SLV2_PLUGININSTANCE_H__
+#define __SLV2_PLUGININSTANCE_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <assert.h>
+#include <dlfcn.h>
+#include <lv2.h>
+#include <slv2/private_types.h>
+#include <slv2/plugininstance.h>
+#include <slv2/plugin.h>
+#include <slv2/port.h>
+
+
+typedef const struct _Instance SLV2Instance;
+
+
+/** \defgroup lib Plugin library access
+ *
+ * An SLV2Instance is an instantiated SLV2Plugin (eg a loaded dynamic
+ * library).  These functions interact with the binary library code only,
+ * they do not read any RDF data files whatsoever.
+ * 
+ * @{
+ */
+
+
+/** Instantiate a plugin.
+ *
+ * The returned object represents shared library objects loaded into memory,
+ * it must be cleaned up with slv2instance_free when no longer
+ * needed.
+ * 
+ * \a plugin is not modified or directly referenced by the returned object
+ * (instances store only a copy of the plugin's URI).
+ * 
+ * \return NULL if instantiation failed.
+ */
+SLV2Instance*
+slv2_plugin_instantiate(const SLV2Plugin*        plugin,
+                        unsigned long            sample_rate,
+                        const LV2_Host_Feature** host_features);
+
+
+/** Free a plugin instance.
+ *
+ * \a instance is invalid after this call.
+ */
+void
+slv2_instance_free(SLV2Instance* instance);
+
+
+#ifndef LIBSLV2_SOURCE
+
+
+/** Get the URI of the plugin which \a instance is an instance of.
+ *
+ * Returned string is shared and must not be modified or deleted.
+ */
+inline const char*
+slv2_instance_get_uri(SLV2Instance* instance)
+{
+	assert(instance);
+	assert(instance->descriptor);
+	
+	return instance->descriptor->URI;
+}
+
+
+/** Connect a port to a data location.
+ *
+ * This may be called regardless of whether the plugin is activated,
+ * activation and deactivation does not destroy port connections.
+ */
+inline void
+slv2_instance_connect_port(SLV2Instance* instance,
+                           unsigned long port_index,
+                           void*         data_location)
+{
+	assert(instance);
+	assert(instance->descriptor);
+	assert(instance->descriptor->connect_port);
+	
+	instance->descriptor->connect_port
+		(instance->lv2_handle, port_index, data_location);
+}
+
+
+/** Activate a plugin instance.
+ *
+ * This resets all state information in the plugin, except for port data
+ * locations (as set by slv2instance_connect_port).  This MUST be called
+ * before calling slv2instance_run.
+ */
+inline void
+slv2_instance_activate(SLV2Instance* instance)
+{
+	assert(instance);
+	assert(instance->descriptor);
+	
+	if (instance->descriptor->activate)
+		instance->descriptor->activate(instance->lv2_handle);
+}
+
+
+/** Run \a instance for \a sample_count frames.
+ *
+ * If the hint lv2:realtimeSafe is set for this plugin, this function is
+ * guaranteed not to block.
+ */
+inline void
+slv2_instance_run(SLV2Instance* instance,
+                  unsigned long sample_count)
+{
+	assert(instance);
+	assert(instance->descriptor);
+	assert(instance->lv2_handle),
+	assert(instance->descriptor->run);
+	
+	instance->descriptor->run(instance->lv2_handle, sample_count);
+}
+
+
+/** Deactivate a plugin instance.
+ *
+ * Note that to run the plugin after this you must activate it, which will
+ * reset all state information (except port connections).
+ */
+inline void
+slv2_instance_deactivate(SLV2Instance* instance)
+{
+	assert(instance);
+	assert(instance->descriptor);
+	assert(instance->lv2_handle);
+	
+	if (instance->descriptor->deactivate)
+		instance->descriptor->deactivate(instance->lv2_handle);
+}
+
+
+/** Get the LV2_Descriptor of the plugin instance.
+ *
+ * Normally hosts should not need to access the LV2_Descriptor directly,
+ * use the slv2instance_* functions.
+ *
+ * The returned descriptor is shared and must not be deleted.
+ */
+inline const LV2_Descriptor*
+slv2_instance_get_descriptor(SLV2Instance* instance)
+{
+	assert(instance);
+	assert(instance->descriptor);
+	
+	return instance->descriptor;
+}
+
+
+/** Get the LV2_Handle of the plugin instance.
+ *
+ * Normally hosts should not need to access the LV2_Handle directly,
+ * use the slv2instance_* functions.
+ * 
+ * The returned handle is shared and must not be deleted.
+ */
+inline LV2_Handle
+slv2_instance_get_handle(SLV2Instance* instance)
+{
+	assert(instance);
+	assert(instance->descriptor);
+	
+	return instance->lv2_handle;
+}
+
+#endif /* LIBSLV2_SOURCE */
+
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+
+#endif /* __SLV2_PLUGININSTANCE_H__ */
+
diff --git a/slv2/pluginlist.h b/slv2/pluginlist.h
new file mode 100644
index 0000000..d29a56d
--- /dev/null
+++ b/slv2/pluginlist.h
@@ -0,0 +1,159 @@
+/* LibSLV2
+ * Copyright (C) 2006 Dave Robillard <drobilla@connect.carleton.ca>
+ *  
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This library 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 General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifndef __SLV2_PLUGINLIST_H__
+#define __SLV2_PLUGINLIST_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+typedef struct _PluginList* SLV2List;
+
+
+/** \defgroup lists Plugin lists
+ *
+ * These functions are for locating plugins installed on the system.
+ *
+ * Normal hosts which just want to easily load plugins by URI are strongly
+ * recommended to simply find all installed plugins with
+ * \ref slv2_list_load_all rather than find and load bundles manually.
+ * 
+ * Functions are provided for hosts that wish to access bundles explicitly and
+ * individually for some reason, as well as make custom lists of plugins from
+ * a selection of bundles.  This is mostly intended for hosts which are
+ * tied to a specific (bundled with the application) bundle.
+ *
+ * @{
+ */
+
+
+/** Create a new, empty plugin list.
+ *
+ * Returned object must be freed with slv2_list_free.
+ */
+SLV2List
+slv2_list_new();
+
+
+/** Free a plugin list.
+ *
+ * Note that all plugins in the list (eg those returned by the get_plugin
+ * functions) will be deleted as well.  It is expected that hosts will
+ * keep the plugin list allocated until they are done with their plugins.
+ * If you want to keep a plugin around, but free the list it came from, you
+ * will have to copy it with slv2_plugin_duplicate().
+ *
+ * \a list is invalid after this call (though it may be used again after a
+ * "list = slv2_list_new()")
+ */
+void
+slv2_list_free(SLV2List list);
+
+
+/** Add all plugins installed on the system to \a list.
+ *
+ * This is the recommended way for hosts to access plugins.  It finds all
+ * plugins on the system using the recommended mechanism.  At the time, this
+ * is by searching the path defined in the environment variable LADSPA2_PATH,
+ * though this is subject to change in the future.  Future versions may, for
+ * example, allow users to specify a plugin whitelist of plugins they would
+ * like to be visible in apps (or conversely a blacklist of plugins they do
+ * not wish to use).
+ *
+ * Use of any of the other functions for locating plugins is highly
+ * discouraged without specific reason to do so.  Use this one.
+ */
+void
+slv2_list_load_all(SLV2List list);
+
+
+/** Add all plugins found in \a search_path to \a list.
+ *
+ * If \a search_path is NULL, \a list will be unmodified.
+ *
+ * Use of this function is not recommended.  Use \ref slv2_list_load_all.
+ *
+ * Returned value must be cleaned up by slv2list_free.
+ */
+void
+slv2_list_load_path(SLV2List    list,
+                    const char* search_path);
+
+
+/** Add all plugins found in the bundle at \a bundle_base_url to \a list.
+ *
+ * \arg bundle_base_url is a fully qualified path to the bundle directory, eg.
+ * "file:///usr/lib/lv2/someBundle"
+ *
+ * Use of this function is <b>strongly</b> discouraged, hosts should not attach
+ * any significance to bundle paths as there are no guarantees they will
+ * remain consistent whatsoever.  This function should only be used by apps
+ * which ship with a special bundle (which it knows exists at some path).
+ * It is <b>not</b> to be used by normal hosts that want to load system
+ * installed plugins.  Use \ref slv2_list_load_all.
+ */
+void
+slv2_list_load_bundle(SLV2List             list,
+                      const unsigned char* bundle_base_url);
+
+
+/** Get the number of plugins in the list.
+ */
+unsigned long
+slv2_list_get_length(const SLV2List list);
+
+
+/** Get a plugin from the list by URI.
+ *
+ * Return value is shared (stored in \a list) and must not be freed or
+ * modified by the caller in any way.
+ * 
+ * \return NULL if plugin with \a url not found in \a list.
+ */
+const SLV2Plugin*
+slv2_list_get_plugin_by_uri(const SLV2List       list,
+                            const unsigned char* uri);
+
+
+/** Get a plugin from the list by index.
+ *
+ * \a index has no significance.  Any \a index not less than
+ * slv2list_get_length(list) will return NULL.  * All plugins in a list can
+ * thus be easily enumerated by repeated calls to this function starting
+ * with \a index 0.
+ *
+ * Return value is shared (stored in \a list) and must not be freed or
+ * modified by the caller in any way.
+ *
+ * \return NULL if \a index out of range.
+ */
+const SLV2Plugin*
+slv2_list_get_plugin_by_index(const SLV2List list,
+                              unsigned long  index);
+
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __SLV2_PLUGINLIST_H__ */
+
diff --git a/slv2/port.h b/slv2/port.h
new file mode 100644
index 0000000..749ea4e
--- /dev/null
+++ b/slv2/port.h
@@ -0,0 +1,116 @@
+/* LibSLV2
+ * Copyright (C) 2006 Dave Robillard <drobilla@connect.carleton.ca>
+ *  
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This library 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 General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifndef __SLV2_PORT_H__
+#define __SLV2_PORT_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "types.h"
+#include "plugin.h"
+
+/** \addtogroup data
+ * @{
+ */
+
+
+/** A port on a plugin.
+ *
+ * The information necessary to use the port is stored here, any extra
+ * information can be queried with slv2port_get_property.
+ */
+/*struct LV2Port {
+	unsigned long index;      ///< Index in ports array
+	char*         short_name; ///< Guaranteed unique identifier
+	char*         type;       ///< eg. lv2:InputControlPort
+	char*         data_type;  ///< eg. lv2:float
+};*/
+
+
+/** Get a property of a port, by port index.
+ *
+ * Return value must be free()'d by caller.
+ */
+SLV2Property
+slv2_port_get_property(SLV2Plugin*   plugin,
+                       unsigned long index,
+                       const uchar*  property);
+
+
+/** Get the symbol of a port given the index.
+ *
+ * The 'symbol' is a short string, a valid C identifier.
+ * Returned string must be free()'d by caller.
+ *
+ * \return NULL when index is out of range
+ */
+uchar*
+slv2_port_get_symbol(SLV2Plugin*   plugin,
+                     unsigned long index);
+
+
+/** Get the class (direction and rate) of a port.
+ */
+enum SLV2PortClass
+slv2_port_get_class(SLV2Plugin*   plugin,
+                    unsigned long index);
+
+
+/** Get the data type of a port.
+ */
+enum SLV2DataType
+slv2_port_get_data_type(SLV2Plugin*   plugin,
+                        unsigned long index);
+
+
+/** Get the default value of a port.
+ *
+ * Only valid for ports with a data type of lv2:float.
+ */
+float
+slv2_port_get_default_value(SLV2Plugin*   plugin, 
+                            unsigned long index);
+
+
+/** Get the minimum value of a port.
+ *
+ * Only valid for ports with a data type of lv2:float.
+ */
+float
+slv2_port_get_minimum_value(SLV2Plugin*   plugin, 
+                            unsigned long index);
+
+
+/** Get the maximum value of a port.
+ *
+ * Only valid for ports with a data type of lv2:float.
+ */
+float
+slv2_port_get_maximum_value(SLV2Plugin*   plugin, 
+                            unsigned long index);
+
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __SLV2_PORT_H__ */
diff --git a/slv2/private_types.h b/slv2/private_types.h
new file mode 100644
index 0000000..849e5a2
--- /dev/null
+++ b/slv2/private_types.h
@@ -0,0 +1,65 @@
+/* LibSLV2
+ * Copyright (C) 2006 Dave Robillard <drobilla@connect.carleton.ca>
+ *  
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This library 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 General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifndef __SLV2_PRIVATE_TYPES_H__
+#define __SLV2_PRIVATE_TYPES_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stddef.h>
+#include <lv2.h>
+
+
+/** Record of an installed/available plugin.
+ *
+ * A simple reference to a plugin somewhere on the system. This just holds
+ * paths of relevant files, the actual data therein isn't loaded into memory.
+ */
+struct _Plugin {
+	unsigned char* plugin_uri;
+	unsigned char* bundle_url; // Bundle directory plugin was loaded from
+	unsigned char* data_url;   // rdfs::seeAlso
+	unsigned char* lib_url;    // lv2:binary
+};
+
+
+/** Instance of a plugin (private type) */
+struct _Instance {
+	// FIXME: copy plugin here for convenience?
+	//struct LV2Plugin*   plugin;
+	const LV2_Descriptor* descriptor;
+	void*                 lib_handle;
+	LV2_Handle            lv2_handle;
+};
+
+
+/** List of references to plugins available for loading (private type) */
+struct _PluginList {
+	size_t           num_plugins;
+	struct _Plugin** plugins;
+};
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __SLV2_PRIVATE_TYPES_H__ */
+
diff --git a/slv2/query.h b/slv2/query.h
new file mode 100644
index 0000000..f1708d7
--- /dev/null
+++ b/slv2/query.h
@@ -0,0 +1,102 @@
+/* LibSLV2
+ * Copyright (C) 2006 Dave Robillard <drobilla@connect.carleton.ca>
+ *  
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This library 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 General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifndef __SLV2_QUERY_H__
+#define __SLV2_QUERY_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+	
+#include <rasqal.h>
+#include "plugin.h"
+#include "types.h"
+
+/** \defgroup query SPARQL query helpers
+ *
+ * This part is in progress, incomplete, a random mishmash of crap that
+ * evolved along with my understanding of this rasqal library.  Nothing
+ * to see here, move long now.  Nothing to see here.
+ *
+ * Eventually this will contain functions that make it convenient for host
+ * authors to query plugins in ways libslv2 doesn't nicely wrap (eg. for
+ * extensions not (yet) supported by libslv2).
+ *
+ * @{
+ */
+
+/** Return a header for a SPARQL query on the given plugin.
+ *
+ * The returned header defines the namespace prefixes used in the standard
+ * (rdf: rdfs: doap: lv2:), plugin: as the plugin's URI, and data: as the
+ * URL of the plugin's RDF (Turtle) data file.
+ *
+ * Example query to get a plugin's doap:name using this header:
+ * 
+ * <code>
+ * SELECT DISTINCT ?value FROM data: WHERE {
+ *     plugin:  doap:name  ?value
+ * }
+ * </code>
+ *
+ * \return an unsigned (UTF-8) string which must be free()'d.
+ */
+unsigned char*
+slv2_query_header(const SLV2Plugin* p);
+
+
+/** Return a language filter for the given variable.
+ *
+ * If the environment variable $LANG is not set, returns NULL.
+ *
+ * \arg variable SPARQL variable, including "?" or "$" (eg "?value").
+ * 
+ * This needs to be put inside the WHERE block, after the triples.
+ * 
+ * eg. FILTER( LANG(?value) = "en" || LANG(?value) = "" )
+ */
+unsigned char*
+slv2_query_lang_filter(const uchar* variable);
+
+
+/** Run a SPARQL query on a plugin's data file.
+ *
+ * String arguments will be concatenated, allowing for variable substitution
+ * etc. (without having to define a token syntax and search the string for
+ * tokens, which would be slow).
+ *
+ * Header from slv2query_header will be prepended to passed query string.
+ * rasqal_init() must be called by the caller before calling this function.
+ */
+rasqal_query_results*
+slv2_plugin_run_query(const SLV2Plugin* p,
+                      const uchar*        query_string, ...);
+
+
+SLV2Property
+slv2_query_get_results(rasqal_query_results* results);
+
+/** @} */
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __SLV2_QUERY_H__ */
+
diff --git a/slv2/slv2.h b/slv2/slv2.h
new file mode 100644
index 0000000..6305f23
--- /dev/null
+++ b/slv2/slv2.h
@@ -0,0 +1,36 @@
+/* LibSLV2
+ * Copyright (C) 2006 Dave Robillard <drobilla@connect.carleton.ca>
+ *  
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This library 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 General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifndef __SLV2_H
+#define __SLV2_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+	
+#include <slv2/types.h>
+#include <slv2/plugin.h>
+#include <slv2/plugininstance.h>
+#include <slv2/pluginlist.h>
+#include <slv2/port.h>
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __SLV2_H */
diff --git a/slv2/types.h b/slv2/types.h
new file mode 100644
index 0000000..b6d71cc
--- /dev/null
+++ b/slv2/types.h
@@ -0,0 +1,66 @@
+/* LibSLV2
+ * Copyright (C) 2006 Dave Robillard <drobilla@connect.carleton.ca>
+ *  
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This library 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 General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifndef __SLV2_TYPES_H__
+#define __SLV2_TYPES_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stddef.h>
+
+
+typedef unsigned char uchar;
+
+
+/* A property, resulting from a query.
+ *
+ * Note that properties may have many values.
+ */
+struct _Property {
+	size_t          num_values;
+	unsigned char** values;
+};
+
+typedef struct _Property* SLV2Property;
+
+
+/** Class (direction and rate) of a port */
+enum SLV2PortClass {
+	SLV2_UNKNOWN_PORT_CLASS,
+	SLV2_CONTROL_RATE_INPUT,  /**< One input value per block */
+	SLV2_CONTROL_RATE_OUTPUT, /**< One output value per block */
+	SLV2_AUDIO_RATE_INPUT,    /**< One input value per frame */
+	SLV2_AUDIO_RATE_OUTPUT    /**< One output value per frame */
+};
+
+
+/** Type contained in a port buffer. */
+enum SLV2DataType {
+	SLV2_DATA_TYPE_FLOAT,  /**< IEEE-754 32-bit floating point number */
+	SLV2_UNKNOWN_DATA_TYPE
+};
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __SLV2_TYPES_H__ */
+