libs/ardour/lv2ext/lv2_persist.h

   1 /*
   2   Copyright (C) 2010-2011 David Robillard <http://drobilla.net>
   3   Copyright (C) 2010 Leonard Ritter <paniq@paniq.org>
   4
   5   This header is free software; you can redistribute it and/or modify it
   6   under the terms of the GNU Lesser General Public License as published
   7   by the Free Software Foundation; either version 2 of the License, or
   8   (at your option) any later version.
   9
  10   This header is distributed in the hope that it will be useful, but WITHOUT
  11   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12   FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
  13   License for more details.
  14
  15   You should have received a copy of the GNU Lesser General Public License
  16   along with this header; if not, write to the Free Software Foundation,
  17   Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307 USA
  18 */
  19
  20 /**
  21    @file
  22    C API for the LV2 Persist extension <http://lv2plug.in/ns/ext/persist>.
  23 */
  24
  25 #ifndef LV2_PERSIST_H
  26 #define LV2_PERSIST_H
  27
  28 #include <stdbool.h>
  29 #include <stdint.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 #define LV2_PERSIST_URI "http://lv2plug.in/ns/ext/persist"
  36
  37 /**
  38    A host-provided function to store a value under a given key.
  39    @param callback_data Must be the callback_data passed to LV2_Persist.save().
  40    @param key The key (predicate) to store @a value under (URI mapped integer).
  41    @param value Pointer to the value (object) to be stored.
  42    @param size The size of the data at @a value in bytes.
  43    @param type The type of @a value (URI mapped integer).
  44    @param pod True iff @a value is POD.
  45    @return 0 on success, otherwise a non-zero error code.
  46
  47    The host passes a callback of this type to LV2_Persist.save().
  48    This callback is called repeatedly by the plugin within
  49    LV2_Persist.save() to store all the key/value records that describe
  50    its current state.
  51
  52    If @a pod is true, @a value is guaranteed to be architecture-independent POD
  53    (i.e. a region of memory that does not contain pointers or references to
  54    non-persistent resources and can safely be copied and stored with a simple
  55    memcpy). Note that this definition of POD is more strict than exclusively
  56    in-memory definitions since the value MUST be architecture independent;
  57    e.g. endianness must be considered (so basic numeric types are typically NOT
  58    POD). Hosts MAY fail to store the value, particularly if it is
  59    non-POD. Plugins MUST gracefully handle this situation, even though state
  60    may not be fully restored. Hosts SHOULD support any POD value, even if the
  61    host does not know anything about its type. Plugins SHOULD express their
  62    state entirely with POD values whenever possible, and use non-POD values
  63    only where necessary. Plugins SHOULD use common RDF types and/or types from
  64    the Atom extension <http://lv2plug.in/ns/ext/atom> whenever possible since
  65    hosts are likely to already contain the necessary implementation.
  66
  67    Note that @a size MUST be > 0, and @a value MUST point to a valid region of
  68    memory @a size bytes long (this is required to make restore unambiguous).
  69
  70    The plugin MUST NOT attempt to use this function outside of the
  71    LV2_Persist.restore() context.
  72 */
  73 typedef int (*LV2_Persist_Store_Function)(
  74         void*          callback_data,
  75         const uint32_t key,
  76         const void*    value,
  77         size_t         size,
  78         uint32_t       type,
  79         bool           pod);
  80
  81 /**
  82    A host-provided function to retrieve a value under a given key.
  83    @param callback_data Must be the callback_data passed to LV2_Persist.restore().
  84    @param key The key (predicate) of the value to retrieve (URI mapped integer).
  85    @param size (Output) If non-NULL, set to the size of the restored value.
  86    @param type (Output) If non-NULL, set to the type of the restored value.
  87    @param pod (Output) If non-NULL, set to true iff @a value is POD.
  88    @return A pointer to the restored value (object), or NULL if no value
  89    has been stored under @a key.
  90
  91    A callback of this type is passed by the host to LV2_Persist.restore(). This
  92    callback is called repeatedly by the plugin within LV2_Persist.restore() to
  93    retrieve the values of any keys it requires to restore its state.
  94
  95    The returned value MUST remain valid until LV2_Persist.restore() returns.
  96
  97    The plugin MUST NOT attempt to use this function, or any value returned from
  98    it, outside of the LV2_Persist.restore() context. Returned values MAY be
  99    copied for later use if necessary, assuming the plugin knows how to
 100    correctly do so (e.g. the value is POD, or the plugin understands the type).
 101 */
 102 typedef const void* (*LV2_Persist_Retrieve_Function)(
 103         void*     callback_data,
 104         uint32_t  key,
 105         size_t*   size,
 106         uint32_t* type,
 107         bool*     pod);
 108
 109 /**
 110    Persist Extension Data.
 111
 112    When the plugin's extension_data is called with argument LV2_PERSIST_URI,
 113    the plugin MUST return an LV2_Persist structure, which remains valid for
 114    the lifetime of the plugin.
 115
 116    The host can use the contained function pointers to save and restore the
 117    state of a plugin instance at any time (provided the threading restrictions
 118    for the given function are met).
 119
 120    The typical use case is to save the plugin's state when a project is
 121    saved, and to restore the state when a project has been loaded. Other
 122    uses are possible (e.g. cloning plugin instances or taking a snapshot
 123    of plugin state).
 124
 125    Stored data is only guaranteed to be compatible between instances of plugins
 126    with the same URI (i.e. if a change to a plugin would cause a fatal error
 127    when restoring state saved by a previous version of that plugin, the plugin
 128    URI MUST change just as it must when ports change incompatibly). Plugin
 129    authors should consider this possibility, and always store sensible data
 130    with meaningful types to avoid such compatibility issues in the future.
 131 */
 132 typedef struct _LV2_Persist {
 133
 134         /**
 135            Save plugin state using a host-provided @a store callback.
 136
 137            @param instance The instance handle of the plugin.
 138            @param store The host-provided store callback.
 139            @param callback_data An opaque pointer to host data, e.g. the map or
 140            file where the values are to be stored. If @a store is called,
 141            this MUST be passed as its callback_data parameter.
 142
 143            The plugin is expected to store everything necessary to completely
 144            restore its state later (possibly much later, in a different
 145            process, on a completely different machine, etc.)
 146
 147            The @a callback_data pointer and @a store function MUST NOT be
 148            used beyond the scope of save().
 149
 150            This function has its own special threading class: it may not be
 151            called concurrently with any "Instantiation" function, but it
 152            may be called concurrently with functions in any other class,
 153            unless the definition of that class prohibits it (e.g. it may
 154            not be called concurrently with a "Discovery" function, but it
 155            may be called concurrently with an "Audio" function. The plugin
 156            is responsible for any locking or lock-free techniques necessary
 157            to make this possible.
 158
 159            Note that in the simple case where state is only modified by
 160            restore(), there are no synchronization issues since save() is
 161            never called concurrently with restore() (though run() may read
 162            it during a save).
 163
 164            Plugins that dynamically modify state while running, however,
 165            must take care to do so in such a way that a concurrent call to
 166            save() will save a consistent representation of plugin state for a
 167            single instant in time.
 168         */
 169         void (*save)(LV2_Handle                 instance,
 170                      LV2_Persist_Store_Function store,
 171                      void*                      callback_data);
 172
 173         /**
 174            Restore plugin state using a host-provided @a retrieve callback.
 175
 176            @param instance The instance handle of the plugin.
 177            @param retrieve The host-provided retrieve callback.
 178            @param callback_data An opaque pointer to host data, e.g. the map or
 179            file from which the values are to be restored. If @a retrieve is
 180            called, this MUST be passed as its callback_data parameter.
 181
 182            The plugin MAY assume a restored value was set by a previous call to
 183            LV2_Persist.save() by a plugin with the same URI.
 184
 185            The plugin MUST gracefully fall back to a default value when a
 186            value can not be retrieved. This allows the host to reset the
 187            plugin state with an empty map.
 188
 189            The @a callback_data pointer and @a store function MUST NOT be used
 190            beyond the scope of restore().
 191
 192            This function is in the "Instantiation" threading class as defined
 193            by LV2. This means it MUST NOT be called concurrently with any other
 194            function on the same plugin instance.
 195         */
 196         void (*restore)(LV2_Handle                    instance,
 197                         LV2_Persist_Retrieve_Function retrieve,
 198                         void*                         callback_data);
 199
 200 } LV2_Persist;
 201
 202 #ifdef __cplusplus
 203 } /* extern "C" */
 204 #endif
 205
 206 #endif /* LV2_PERSIST_H */