clap

commit 7eff950840027cbf0711c4f9f1a949780493ff6d
parent 0404e6527d06823c41fb6a39b4e3dc8e91bc0a3c
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date:   Mon, 28 Nov 2022 19:03:12 +0100

Merge pull request #193 from abique/resource-directory

resource directory extension
Diffstat:
A
include/clap/ext/draft/resource-directory.h
 | 
85
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

1 file changed, 85 insertions(+), 0 deletions(-)
diff --git a/include/clap/ext/draft/resource-directory.h b/include/clap/ext/draft/resource-directory.h
@@ -0,0 +1,85 @@
+#pragma once
+
+#include "../../plugin.h"
+
+static CLAP_CONSTEXPR const char CLAP_EXT_RESOURCE_DIRECTORY[] = "clap.resource-directory.draft/0";
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// @page Resource Directory
+///
+/// This extension provides a way for the plugin to store its resources as file in a directory
+/// provided by the host and recover them later on.
+///
+/// The plugin **must** store relative path in its state toward resource directories.
+///
+/// Resource sharing:
+/// - shared directory is shared among all plugin instances, hence mostly appropriate for read-only
+/// content
+///   -> suitable for read-only content
+/// - exclusive directory is exclusive to the plugin instance
+///   -> if the plugin, then its exclusive directory must be duplicated too
+///   -> suitable for read-write content
+///
+/// Keeping the shared directory clean:
+/// - to avoid clashes in the shared directory, plugins are encourraged to organize their files in
+///   sub-folders, for example create one subdirectory using the vendor name
+/// - don't use symbolic links or hard links which points outside of the directory
+///
+/// Resource life-time:
+/// - exclusive folder content is managed by the plugin instance
+/// - exclusive folder content is deleted when the plugin instance is removed from the project
+/// - shared folder content isn't managed by the host, until all plugins using the shared directory
+///   are removed from the project
+///
+/// Note for the host
+/// - try to use the filesytem's copy-on-write feature when possible for reducing exclusive folder
+///   space usage on duplication
+/// - host can "garbage collect" the files in the shared folder using:
+///     clap_plugin_resource_directory.get_files_count()
+///     clap_plugin_resource_directory.get_file_path()
+///   but be **very** careful before deleting any resources
+
+typedef struct clap_plugin_resource_directory {
+   // Sets the directory in which the plugin can save its resources.
+   // The directory remains valid until it is overriden or the plugin is destroyed.
+   // If path is null or blank, it clears the directory location.
+   // path must be absolute.
+   // [main-thread]
+   void(CLAP_ABI *set_directory)(const clap_plugin_t *plugin, const char *path, bool is_shared);
+
+   // Asks the plugin to put its resources into the resources directory.
+   // It is not necessary to collect files which belongs to the plugin's
+   // factory content unless the param all is true.
+   // [main-thread]
+   void(CLAP_ABI *collect)(const clap_plugin_t *plugin, bool all);
+
+   // Returns the number of files used by the plugin in the shared resource folder.
+   // [main-thread]
+   uint32_t(CLAP_ABI *get_files_count)(const clap_plugin_t *plugin);
+
+   // Retrieves relative file path to the resources directory.
+   // @param path writable memory to store the path
+   // @param path_size number of available bytes in path
+   // Returns the number of bytes in the path, or -1 on error
+   // [main-thread]
+   int32_t(CLAP_ABI* get_file_path)(const clap_plugin_t *plugin, uint32_t index, char *path, uint32_t path_size);
+} clap_plugin_resource_directory_t;
+
+typedef struct clap_host_resource_directory {
+   // Request the host to setup a resource directory with the specified sharing.
+   // Returns true if the host will perform the request.
+   // [main-thread]
+   bool(CLAP_ABI *request_directory)(const clap_host *host, bool is_shared);
+
+   // Tell the host that the resource directory of the specified sharing is no longer required.
+   // If is_shared = false, then the host may delete the directory content.
+   // [main-thread]
+   void(CLAP_ABI *release_directory)(const clap_host *host, bool is_shared);
+} clap_host_resource_directory_t;
+
+#ifdef __cplusplus
+}
+#endif