aboutsummaryrefslogtreecommitdiffstats
path: root/ext/persist.lv2/persist.h
diff options
context:
space:
mode:
Diffstat (limited to 'ext/persist.lv2/persist.h')
-rw-r--r--ext/persist.lv2/persist.h97
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.