libs/ardour/lv2ext/lv2_persist.h

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