Use separate POD and portable flags instead of boolean pod.

Add subject to property store/retrieve functions.

1 files changed, 63 insertions, 34 deletions

diff --git a/ext/persist.lv2/persist.h b/ext/persist.lv2/persist.h
index 5ed6c45..17478e8 100644
--- a/ext/persist.lv2/persist.h
+++ b/ext/persist.lv2/persist.h
@@ -35,34 +35,59 @@ extern "C" {
 #define LV2_PERSIST_URI "http://lv2plug.in/ns/ext/persist"
 
 /**
-   A host-provided function to store a value under a given key.
+   Flags describing value characteristics.
+
+   These flags are used along with the value's type URI to determine how to
+   (de-)serialise the value data, or whether it is even possible to do so.
+*/
+typedef enum {
+
+	/**
+	   Plain Old Data.
+
+	   Values with this flag contain no references to non-persistent or
+	   non-global resources (e.g. pointers, handles, local paths, etc.). It is
+	   safe to copy POD values with a simple memcpy and store them for use at
+	   any time in the future on a machine with a compatible architecture
+	   (e.g. the same endianness and alignment).
+
+	   Implementations MUST NOT attempt to copy or serialise a non-POD value if
+	   they do not understand its type (and thus know how to correctly do so).
+	*/
+	LV2_PERSIST_IS_POD = 1,
+
+	/**
+	   Portable (architecture independent) data.
+
+	   Values with this flag are in a format that is usable on any
+	   architecture, i.e. if the value is saved on one machine, it can safely
+	   be restored on another machine regardless of endianness, alignment, etc.
+	*/
+	LV2_PERSIST_IS_PORTABLE = 1 << 1
+
+} LV2_Persist_Flags;
+
+/**
+   A host-provided function to store a property.
    @param callback_data Must be the callback_data passed to LV2_Persist.save().
+   @param subject The subject of this property (URI), or 0 for plugin instance.
    @param key The key (predicate) to store @a value under (URI mapped integer).
    @param value Pointer to the value (object) to be stored.
    @param size The size of the data at @a value in bytes.
-   @param type The type of @a value (URI mapped integer).
-   @param pod True iff @a value is POD.
+   @param type The type of @a value (URI).
+   @param flags LV2_Persist_Flags for @a value.
    @return 0 on success, otherwise a non-zero error code.
 
-   The host passes a callback of this type to LV2_Persist.save().
-   This callback is called repeatedly by the plugin within
-   LV2_Persist.save() to store all the key/value records that describe
-   its current state.
-
-   If @a pod is true, @a value is guaranteed to be architecture-independent POD
-   (i.e. a region of memory that does not contain pointers or references to
-   non-persistent resources and can safely be copied and stored with a simple
-   memcpy). Note that this definition of POD is more strict than exclusively
-   in-memory definitions since the value MUST be architecture independent;
-   e.g. endianness must be considered (so basic numeric types are typically NOT
-   POD). Hosts MAY fail to store the value, particularly if it is
-   non-POD. Plugins MUST gracefully handle this situation, even though state
-   may not be fully restored. Hosts SHOULD support any POD value, even if the
-   host does not know anything about its type. Plugins SHOULD express their
-   state entirely with POD values whenever possible, and use non-POD values
-   only where necessary. Plugins SHOULD use common RDF types and/or types from
-   the Atom extension <http://lv2plug.in/ns/ext/atom> whenever possible since
-   hosts are likely to already contain the necessary implementation.
+   The host passes a callback of this type to LV2_Persist.save(). This callback
+   is called repeatedly by the plugin within LV2_Persist.save() to store all
+   the statements that describe its current state.
+
+   The host MAY fail to store a statement if the type is not understood and is
+   not LV2_PERSIST_IS_POD and/or LV2_PERSIST_IS_PORTABLE. Implementations
+   are encouraged to use POD and portable values (e.g. string literals)
+   wherever possible, and use common types (e.g. types from
+   http://lv2plug.in/ns/ext/atom) regardless, since hosts are likely to already
+   contain the necessary implementation.
 
    Note that @a size MUST be > 0, and @a value MUST point to a valid region of
    memory @a size bytes long (this is required to make restore unambiguous).
@@ -71,40 +96,44 @@ extern "C" {
    LV2_Persist.restore() context.
 */
 typedef int (*LV2_Persist_Store_Function)(
-	void*          callback_data,
-	const uint32_t key,
-	const void*    value,
-	size_t         size,
-	uint32_t       type,
-	bool           pod);
+	void*       callback_data,
+	uint32_t    subject,
+	uint32_t    key,
+	const void* value,
+	size_t      size,
+	uint32_t    type,
+	uint32_t    flags);
 
 /**
-   A host-provided function to retrieve a value under a given key.
+   A host-provided function to retrieve a property.
    @param callback_data Must be the callback_data passed to LV2_Persist.restore().
-   @param key The key (predicate) of the value to retrieve (URI mapped integer).
+   @param subject The subject of the property (URI), or 0 for plugin instance.
+   @param key The key (predicate) of the property to retrieve (URI).
    @param size (Output) If non-NULL, set to the size of the restored value.
    @param type (Output) If non-NULL, set to the type of the restored value.
-   @param pod (Output) If non-NULL, set to true iff @a value is POD.
+   @param flags (Output) If non-NULL, set to the LV2_Persist_Flags for
+   the returned value.
    @return A pointer to the restored value (object), or NULL if no value
    has been stored under @a key.
 
    A callback of this type is passed by the host to LV2_Persist.restore(). This
    callback is called repeatedly by the plugin within LV2_Persist.restore() to
-   retrieve the values of any keys it requires to restore its state.
+   retrieve any properties it requires to restore its state.
 
    The returned value MUST remain valid until LV2_Persist.restore() returns.
 
    The plugin MUST NOT attempt to use this function, or any value returned from
    it, outside of the LV2_Persist.restore() context. Returned values MAY be
    copied for later use if necessary, assuming the plugin knows how to
-   correctly do so (e.g. the value is POD, or the plugin understands the type).
+   do so correctly (e.g. the value is POD, or the plugin understands the type).
 */
 typedef const void* (*LV2_Persist_Retrieve_Function)(
 	void*     callback_data,
+	uint32_t  subject,
 	uint32_t  key,
 	size_t*   size,
 	uint32_t* type,
-	bool*     pod);
+	uint32_t* flags);
 
 /**
    Persist Extension Data.