Create new Message extension, and remove message type definition from Atom extension.

Clean up Atom extension and define more struct types in header.

5 files changed, 223 insertions, 89 deletions

diff --git a/ext/atom.lv2/atom.h b/ext/atom.lv2/atom.h
index 51fb817..e5990c9 100644
--- a/ext/atom.lv2/atom.h
+++ b/ext/atom.lv2/atom.h
@@ -75,46 +75,29 @@ typedef struct _LV2_Atom {
 } LV2_Atom;
 
 /** Reference, an LV2_Atom with type 0 */
-typedef LV2_Atom LV2_Reference;
-
-/** The body of an LV2_Atom with type atom:Vector
- */
-typedef struct _LV2_Vector_Body {
-
-	/** The size of each element in the vector */
-	uint16_t elem_count;
-
-	/** The type of each element in the vector */
-	uint16_t elem_type;
-
-	/** Elements follow here */
-	uint8_t elems[];
-
-} LV2_Vector_Body;
+typedef LV2_Atom LV2_Atom_Reference;
 
+/** The body of an LV2_Atom with type atom:Vector */
+typedef struct _LV2_Atom_Vector {
+	uint16_t elem_count; /**< The size of each element in the vector */
+	uint16_t elem_type;  /**< The type of each element in the vector */
+	uint8_t  elems[];    /**< Elements follow here */
+} LV2_Atom_Vector;
 
-/** The body of an LV2_Atom with type atom:Triple
- */
-typedef struct _LV2_Triple_Body {
-	uint32_t subject;
-	uint32_t predicate;
-	LV2_Atom object;
-} LV2_Triple_Body;
-
+/** The body of an LV2_Atom with type atom:Property */
+typedef struct _LV2_Atom_Property {
+	uint32_t predicate; /**< Predicate (key) of RDF triple (URI mapped int) */
+	LV2_Atom object;    /**< Object (value) of RDF triple */
+} LV2_Atom_Property;
 
-/** The body of an LV2_Atom with type atom:Message
- */
-typedef struct _LV2_Message_Body {
-	uint32_t selector; /***< Selector URI mapped to integer */
-	LV2_Atom triples; /***< Always an atom:Triples */
-} LV2_Message_Body;
+/** The body of an LV2_Atom with type atom:Triple */
+typedef struct _LV2_Atom_Triple {
+	uint32_t          subject;  /**< Subject of RDF triple (URI mapped integer) */
+	LV2_Atom_Property property; /** Property (predicate and object) of subject */
+} LV2_Atom_Triple;
 
 
-/* Everything below here is related to blobs, which are dynamically allocated
- * atoms that are not necessarily POD.  This functionality is optional,
- * hosts may support atoms without implementing blob support.
- * Blob support is an LV2 Feature.
- */
+/* Optional Blob Support */
 
 
 typedef void* LV2_Blob_Data;
@@ -122,16 +105,16 @@ typedef void* LV2_Blob_Data;
 /** Dynamically Allocated LV2 Blob.
  *
  * This is a blob of data of any type, dynamically allocated in memory.
- * Unlike an LV2_Atom, a blob is not necessarily POD.  Plugins may only
+ * Unlike an LV2_Atom, a blob is not necessarily POD.  Plugins MUST only
  * refer to blobs via a Reference (an LV2_Atom with type 0), there is no
- * way for a plugin to directly create, copy, or destroy a Blob.
+ * way for a plugin to directly copy or destroy a Blob.
  */
 typedef struct _LV2_Blob {
 
 	/** Pointer to opaque data.
 	 *
 	 * Plugins MUST NOT interpret this data in any way.  Hosts may store
-	 * whatever information they need to associate with references here.
+	 * whatever information they need to associate with blobs here.
 	 */
 	LV2_Blob_Data data;
 
@@ -159,72 +142,88 @@ typedef void* LV2_Blob_Support_Data;
 
 typedef void (*LV2_Blob_Destroy)(LV2_Blob* blob);
 
-/** The data field of the LV2_Feature for the LV2 Atom extension.
+/** The data field of the LV2_Feature for atom:BlobSupport.
  *
- * A host which supports this extension must pass an LV2_Feature struct to the
- * plugin's instantiate method with 'URI' "http://lv2plug.in/ns/ext/atom" and
- * 'data' pointing to an instance of this struct.  All fields of this struct,
- * MUST be set to non-NULL values by the host (except possibly data).
+ * A host which supports blobs must pass an LV2_Feature struct to the
+ * plugin's instantiate method with 'URI' equal to
+ * "http://lv2plug.in/ns/ext/atom#BlobSupport" and 'data' pointing to an
+ * instance of this struct.  All fields of this struct MUST be set to
+ * non-NULL values by the host, except possibly 'data'.
  */
 typedef struct {
 
-	/** Pointer to opaque data.
+	/** Pointer to opaque host data.
 	 *
 	 * The plugin MUST pass this to any call to functions in this struct.
-	 * Otherwise, it must not be interpreted in any way.
+	 * Otherwise, the plugin MUST NOT interpret this value in any way.
 	 */
 	LV2_Blob_Support_Data data;
 
 	/** The size of a reference, in bytes.
 	 *
 	 * This value is provided by the host so plugins can allocate large
-	 * enough chunks of memory to store references.
+	 * enough chunks of memory to store references.  Note a reference is
+	 * an LV2_Atom with type atom:Reference, hence ref_size is a
+	 * uint16, like LV2_Atom.size.
 	 */
-	size_t reference_size;
+	uint16_t ref_size;
 
 	/** Initialize a reference to point to a newly allocated Blob.
 	 *
 	 * @param data Must be the data member of this struct.
-	 * @param reference Pointer to an area of memory at least as large as
-	 *     the reference_size field of this struct.  On return, this will
-	 *     be the unique reference to the new blob which is owned by the
-	 *     caller.  Caller MUST NOT pass a valid reference.
-	 * @param destroy Function to destroy a blob of this type.  This function
+	 * @param ref Pointer to an area of memory at least as large as
+	 *     the ref_size field of this struct.  On return, this will
+	 *     be the unique reference to the new blob, which is owned by the
+	 *     caller.  Assumed to be uninitialised, i.e. the caller MUST NOT
+	 *     pass a valid (owned) reference since this could cause a memory leak.
+	 * @param destroy Function to destroy this blob.  This function
 	 *     MUST clean up any resources contained in the blob, but MUST NOT
-	 *     attempt to free the memory pointed to by its LV2_Blob* parameter.
+	 *     attempt to free the memory pointed to by its LV2_Blob* parameter
+	 *     (since this is allocated by the host).
 	 * @param type Type of blob to allocate (URI mapped integer).
 	 * @param size Size of blob to allocate in bytes.
 	 */
-	void (*lv2_blob_new)(LV2_Blob_Support_Data data,
-	                     LV2_Reference*        reference,
-	                     LV2_Blob_Destroy      destroy_func,
-	                     uint32_t              type,
-	                     size_t                size);
+	void (*blob_new)(LV2_Blob_Support_Data data,
+	                 LV2_Atom_Reference*   ref,
+	                 LV2_Blob_Destroy      destroy,
+	                 uint32_t              type,
+	                 size_t                size);
 
 	/** Return a pointer to the Blob referred to by @a ref.
 	 *
 	 * The returned value MUST NOT be used in any way other than by calling
 	 * methods defined in LV2_Blob (e.g. it MUST NOT be copied or destroyed).
 	 */
-	LV2_Blob* (*lv2_reference_get)(LV2_Blob_Support_Data data,
-	                               LV2_Reference*        ref);
+	LV2_Blob* (*ref_get)(LV2_Blob_Support_Data data,
+	                     LV2_Atom_Reference*   ref);
 
 	/** Copy a reference.
 	 * This copies a reference but not the blob it refers to,
 	 * i.e. after this call @a dst and @a src refer to the same LV2_Blob.
 	 */
-	void (*lv2_reference_copy)(LV2_Blob_Support_Data data,
-	                           LV2_Reference*        dst,
-	                           LV2_Reference*        src);
+	void (*ref_copy)(LV2_Blob_Support_Data data,
+	                 LV2_Atom_Reference*   dst,
+	                 LV2_Atom_Reference*   src);
 
 	/** Reset (release) a reference.
-	 * After this call, @a ref is invalid.  Use of this function is only
-	 * necessary if a plugin makes a copy of a reference it does not later
-	 * send to an output (which transfers ownership to the host).
+	 * After this call, @a ref is invalid.  Implementations must be sure to
+	 * call this function when necessary, or memory leaks will result.  The
+	 * specific times this is necessary MUST be defined by any extensions that
+	 * define a mechanism for transporting atoms.  The standard semantics are:
+	 * <ul><li>Whenever passed a Reference (e.g. via a Port) and run, the
+	 * plugin owns that reference.</li>
+	 * <li>The plugin owns any reference it creates (e.g. by using blob_new or
+	 * ref_copy).</li>
+	 * <li>For any reference it owns, the plugin MUST either:
+	 *   <ul><li>Copy the reference and store it (to be used in future runs and
+	 *   released later).</li>
+	 *   <li>Copy the reference to an output port exactly once.</li>
+	 *   <li>Release it with ref_reset.</li></ul></li>
+	 * </ul>
 	 */
-	void (*lv2_reference_reset)(LV2_Blob_Support_Data data,
-	                            LV2_Reference*        ref);
-
+	void (*ref_reset)(LV2_Blob_Support_Data data,
+	                  LV2_Atom_Reference*   ref);
+	
 } LV2_Blob_Support;
 
 
diff --git a/ext/atom.lv2/atom.ttl b/ext/atom.lv2/atom.ttl
index 0173d51..e6ed6b9 100644
--- a/ext/atom.lv2/atom.ttl
+++ b/ext/atom.lv2/atom.ttl
@@ -1,3 +1,4 @@
+
 # LV2 Atom Extension
 # Copyright (C) 2007-2010 David Robillard <d@drobilla.net>
 # 
@@ -122,23 +123,6 @@ always 4.
 """ .
 
 
-atom:Message a atom:AtomType ;
-	rdfs:label "Message" ;
-	rdfs:comment """
-A message is a communication from one component to another.  Messages
-consist of a selector URI, and a set of RDF triples.  The selector URI
-dictates how the triples are to be interpreted (e.g. the selector can
-be used as a "verb" to build commands).
-
-The payload of a message is always an atom:Triples so hosts and plugins can
-always work with message data (e.g. to serialise for saved state or an undo
-stack), even if they do not specifically understand a particular message.
-
-In memory, a Message is simply a uint32_t selector (a URI mapped integer)
-followed by an atom:Triples.
-""" .
-
-
 atom:Vector a atom:AtomType ;
 	rdfs:label "Vector" ;
 	rdfs:comment """
@@ -171,14 +155,28 @@ int32_t  contents[42] = ...
 """ .
 
 
+atom:Property a atom:AtomType ;
+	rdfs:label "RDF property of some object" ;
+	rdfs:comment """
+A description in RDF of a single property for some object (i.e. an RDF
+statement with only predicate and object defined).
+<pre>
+uint32_t predicate;
+LV2_Atom object;
+</pre>
+""" .
+
+
 atom:Triple a atom:AtomType ;
 	rdfs:label "RDF triple" ;
 	rdfs:comment """
 A single RDF triple.
 
-The subject and predicate of an RDF triple are implicitly URIs, thus in an
-atom:Triple they are stored as URI mapped integers with type tags and sizes
-omitted.
+The subject and predicate of a Triple are implicitly URIs, thus they are stored
+as URI mapped integers with type and size ommitted (i.e. a single uint32_t).
+
+An atom:Triple is memory is a uint32_t subject immediately followed by the
+body of an atom:Property.
 
 An atom:Triple in memory is two uint32_t's followed by an LV2_Atom:
 <pre>
@@ -247,6 +245,7 @@ atom:Float64 a atom:AtomType ; rdfs:label "64-bit Floating Point Number" .
 atom:blobSupport a lv2:Feature ;
 	rdfs:label "Blob support" ;
 	rdfs:comment """
+    
 Support for dynamically allocated blobs.  If a host supports this feature, it
 MUST pass an LV2_Feature with URI http://lv2plug.in/ns/ext/atom#blobSupport
 and a pointer to LV2_Blob_Support as data to the plugin's instantiate method.
diff --git a/ext/message.lv2/manifest.ttl b/ext/message.lv2/manifest.ttl
new file mode 100644
index 0000000..2e0704a
--- /dev/null
+++ b/ext/message.lv2/manifest.ttl
@@ -0,0 +1,7 @@
+@prefix lv2:  <http://lv2plug.in/ns/lv2core#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+<http://lv2plug.in/ns/ext/message>
+	a lv2:Specification ;
+	rdfs:seeAlso <message.ttl> .
+
diff --git a/ext/message.lv2/message.h b/ext/message.lv2/message.h
new file mode 100644
index 0000000..45391c3
--- /dev/null
+++ b/ext/message.lv2/message.h
@@ -0,0 +1,46 @@
+/* lv2_message.h - C header file for the LV2 Message extension.
+ * Copyright (C) 2010 David Robillard <http://drobilla.net>
+ *
+ * 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 Message extension <http://lv2plug.in/ns/ext/message>.
+ */
+
+#ifndef LV2_MESSAGE_H
+#define LV2_MESSAGE_H
+
+#define LV2_MESSAGE_URI "http://lv2plug.in/ns/ext/message"
+
+#include <stdint.h>
+#include <stddef.h>
+
+#include "lv2/http/lv2plug.in/ns/ext/atom/atom.h"
+
+/** An LV2 Message.
+ *
+ * A "Message" is an Atom of type message:Message.  The payload of a Message
+ * is a key/value dictionary with URI mapped integer keys (uint32_t), followed
+ * by a key/value dictionary with URI mapped integer keys and Atom values
+ * (atom:Blank, i.e. LV2_).
+ */
+typedef struct _LV2_Message_Message {
+	uint32_t selector; /***< Selector URI mapped to integer */
+	LV2_Atom triples; /***< Always an atom:Triples */
+} LV2_Message_Message;
+
+#endif /* LV2_MESSAGE_H */
+
diff --git a/ext/message.lv2/message.ttl b/ext/message.lv2/message.ttl
new file mode 100644
index 0000000..03072f3
--- /dev/null
+++ b/ext/message.lv2/message.ttl
@@ -0,0 +1,83 @@
+# LV2 Message Extension
+# Copyright (C) 2007-2010 David Robillard <d@drobilla.net>
+# 
+# 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.
+
+@prefix message: <http://lv2plug.in/ns/ext/message#> .
+@prefix atom:    <http://lv2plug.in/ns/ext/atom#> .
+@prefix doap:    <http://usefulinc.com/ns/doap#> .
+@prefix foaf:    <http://xmlns.com/foaf/0.1/> .
+@prefix lv2:     <http://lv2plug.in/ns/lv2core#> .
+@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd:     <http://www.w3.org/2001/XMLSchema> .
+
+<http://lv2plug.in/ns/ext/message>
+	a lv2:Specification ;
+    doap:name "LV2 Message" ;
+    doap:maintainer [
+        a foaf:Person ;
+        foaf:name     "David Robillard" ;
+        foaf:homepage <http://drobilla.net/> ;
+        rdfs:seeAlso  <http://drobilla.net/drobilla.rdf>
+    ] ;
+	rdfs:comment """
+This extension defines the format for "messages" which can be used to
+dynamically control an LV2 plugin instance at runtime.  Messages are useful
+for any kind of plugin control that does not fit well with control ports.
+Plugins can both receive and send messages (and thus send messages to each
+other) via any mechanism.
+
+This extension requires the host to support the <a
+href="http://lv2plug.in/ns/ext/uri-map">LV2 URI Map</a> extension, and the
+<a href="http://lv2plug.in/ns/ext/atom">LV2 Atom</a> extension.
+""" .
+
+
+message:MessageType a rdfs:Class ;
+	rdfs:label   "LV2 Message Type" ;
+	rdfs:comment """
+Base class for all types of LV2 Message.
+
+A type of message, which must be a resource (i.e. have a URI).  This URI
+is used as the selector component of a Message and is used by receivers
+to interpret the meaning of messages (e.g. which components are present).
+""" .
+
+message:Message a atom:AtomType ;
+	rdfs:label "Message" ;
+	rdfs:comment """
+A message is a communication from one component to another.  Messages consist
+of a selector URI, and a key/value dictionary.  Keys in the dictionary are
+URI mapped integers, and values are Atoms. The selector URI dictates how
+the message is to be interpreted (e.g. the selector can be used as a "verb"
+to build commands).
+
+Messages are simple to serialise in many different formats (e.g. any RDF
+serialisation including LV2 Turtle files, JSON, XML, etc) making network
+transparency and persistence simple, assuming the implementation can
+serialise Atoms.
+
+Because all messages have a standard format, plugins and hosts can store,
+communicate, or otherwise work with messages even if they do not understand
+that particular message's selector.
+
+In memory, a Message is simply a uint32_t selector (a URI mapped integer)
+followed by an atom:Blank.
+""" .