<commit_before>/*
  Copyright (C) 2010-2011 <NAME> <http://drobilla.net>
  Copyright (C) 2010 <NAME> <<EMAIL>>

  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 API for the LV2 Persist extension <http://lv2plug.in/ns/ext/persist>.
*/

#ifndef LV2_PERSIST_H
#define LV2_PERSIST_H

#include <stdbool.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define LV2_PERSIST_URI "http://lv2plug.in/ns/ext/persist"

/**
   A host-provided function to store a value under a given key.
   @param callback_data Must be the callback_data passed to LV2_Persist.save().
   @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.
   @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.

   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).

   The plugin MUST NOT attempt to use this function outside of the
   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);

/**
   A host-provided function to retrieve a value under a given key.
   @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 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.
   @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.

   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).
*/
typedef const void* (*LV2_Persist_Retrieve_Function)(
	void*     callback_data,
	uint32_t  key,
	size_t*   size,
	uint32_t* type,
	bool*     pod);

/**
   Persist Extension Data.

   When the plugin's extension_data is called with argument LV2_PERSIST_URI,
   the plugin MUST return an LV2_Persist structure, which remains valid for
   the lifetime of the plugin.

   The host can use the contained function pointers to save and restore the
   state of a plugin instance at any time (provided the threading restrictions
   for the given function are met).

   The typical use case is to save the plugin's state when a project is
   saved, and to restore the state when a project has been loaded. Other
   uses are possible (e.g. cloning plugin instances or taking a snapshot
   of plugin state).

   Stored data is only guaranteed to be compatible between instances of plugins
   with the same URI (i.e. if a change to a plugin would cause a fatal error
   when restoring state saved by a previous version of that plugin, the plugin
   URI MUST change just as it must when ports change incompatibly). Plugin<commit_msg>Use separate POD and portable flags instead of boolean pod. Add subject to property store/retrieve functions.<commit_after>/*
  Copyright (C) 2010-2011 <NAME> <http://drobilla.net>
  Copyright (C) 2010 <NAME> <<EMAIL>>

  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 API for the LV2 Persist extension <http://lv2plug.in/ns/ext/persist>.
*/

#ifndef LV2_PERSIST_H
#define LV2_PERSIST_H

#include <stdbool.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define LV2_PERSIST_URI "http://lv2plug.in/ns/ext/persist"

/**
   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).
   @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 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).

   The plugin MUST NOT attempt to use this function outside of the
   LV2_Persist.restore() context.
*/
typedef int (*LV2_Persist_Store_Function)(
	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 property.
   @param callback_data Must be the callback_data passed to LV2_Persist.restore().
   @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 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 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
   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,
	uint32_t* flags);

/**
   Persist Extension Data.

   When the plugin's extension_data is called with argument LV2_PERSIST_URI,
   the plugin MUST return an LV2_Persist structure, which remains valid for
   the lifetime of the plugin.

   The host can use the contained function pointers to save and restore the
   state of a plugin instance at any time (provided the threading restrictions
   for the given function are met).

   The typical use case is to save the plugin's state when a project is
   saved, and to restore the state when a project has been loaded. Other
   uses are possible (e.g. cloning plugin instances or taking a snapshot
   of plugin state).

   Stored data is only guaranteed to be compatible between instances of plugins
   with the same URI (i.e. if a change to a plugin would cause a fatal error
   when restoring state saved by a previous version of that plugin, the plugin
   URI MUST change just as it must when ports change incompatibly). Plugin
{'fraction_non_alphanumeric': 0.05569493226292022, 'fraction_numerical': 0.011205887272119084, 'mean_word_length': 3.516238670694864, 'pattern_counts': {'":': 0, '<': 22, '<?xml version=': 0, '>': 22, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2611467', 'n_tokens_mistral': 3488, 'n_tokens_neox': 3277, 'n_words': 1751}