diff options
Diffstat (limited to 'slv2/plugin.h')
| -rw-r--r-- | slv2/plugin.h | 331 |
1 files changed, 0 insertions, 331 deletions
diff --git a/slv2/plugin.h b/slv2/plugin.h deleted file mode 100644 index f688626..0000000 --- a/slv2/plugin.h +++ /dev/null @@ -1,331 +0,0 @@ -/* SLV2 - * Copyright (C) 2007-2011 David Robillard <http://drobilla.net> - * - * This library is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License as published by the Free - * Software Foundation; either version 2 of the License, or (at your option) - * any later version. - * - * This library 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 General Public License - * for more details. - * - * You should have received a copy of the GNU General Public License along - * with this program; if not, write to the Free Software Foundation, Inc., - * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - */ - -#ifndef __SLV2_PLUGIN_H__ -#define __SLV2_PLUGIN_H__ - -#ifdef __cplusplus -extern "C" { -#endif - -#include <stdint.h> -#include <stdbool.h> -#include "slv2/types.h" -#include "slv2/port.h" -#include "slv2/collections.h" - -/** @defgroup slv2_data Plugin data access - * - * These functions work exclusively with the plugin's RDF data, - * they do not access the plugin's shared library in any way. - * - * An SLV2Plugin contains an in-memory cache of the plugin data, loaded - * on demand. Duplicating plugins should be avoided when possible for - * performance reasons. - * - * @{ - */ - -/** Check if this plugin is valid. - * This is not a rigorous validator, but can be used to reject some malformed - * plugins that could cause bugs (e.g. plugins with missing required fields). - * - * Note that normal hosts do NOT need to use this - slv2 does not - * load invalid plugins into plugin lists. This is included for plugin - * testing utilities, etc. - * @return true iff @a plugin is valid. - */ -SLV2_API -bool -slv2_plugin_verify(SLV2Plugin plugin); - -/** Get the URI of @a plugin. - * Any serialization that refers to plugins should refer to them by this. - * Hosts SHOULD NOT save any filesystem paths, plugin indexes, etc. in saved - * files; save only the URI. - * - * The URI is a globally unique identifier for one specific plugin. Two - * plugins with the same URI are compatible in port signature, and should - * be guaranteed to work in a compatible and consistent way. If a plugin - * is upgraded in an incompatible way (eg if it has different ports), it - * MUST have a different URI than it's predecessor. - * - * @return A shared URI value which must not be modified or freed. - */ -SLV2_API -SLV2Value -slv2_plugin_get_uri(SLV2Plugin plugin); - -/** Get the (resolvable) URI of the plugin's "main" bundle. - * This returns the URI of the bundle where the plugin itself was found. - * Note that the data for a plugin may be spread over many bundles, that is, - * slv2_plugin_get_data_uris may return URIs which are not within this bundle. - * - * Typical hosts should not need to use this function. - * Note this always returns a fully qualified URI. If you want a local - * filesystem path, use slv2_uri_to_path. - * @return a shared string which must not be modified or freed. - */ -SLV2_API -SLV2Value -slv2_plugin_get_bundle_uri(SLV2Plugin plugin); - -/** Get the (resolvable) URIs of the RDF data files that define a plugin. - * Typical hosts should not need to use this function. - * Note this always returns fully qualified URIs. If you want local - * filesystem paths, use slv2_uri_to_path. - * @return a list of complete URLs eg. "file:///foo/ABundle.lv2/aplug.ttl", - * which is shared and must not be modified or freed. - */ -SLV2_API -SLV2Values -slv2_plugin_get_data_uris(SLV2Plugin plugin); - -/** Get the (resolvable) URI of the shared library for @a plugin. - * Note this always returns a fully qualified URI. If you want a local - * filesystem path, use slv2_uri_to_path. - * @return a shared string which must not be modified or freed. - */ -SLV2_API -SLV2Value -slv2_plugin_get_library_uri(SLV2Plugin plugin); - -/** Get the name of @a plugin. - * This returns the name (doap:name) of the plugin. The name may be - * translated according to the current locale, this value MUST NOT be used - * as a plugin identifier (use the URI for that). - * Returned value must be freed by the caller. - */ -SLV2_API -SLV2Value -slv2_plugin_get_name(SLV2Plugin plugin); - -/** Get the class this plugin belongs to (ie Filters). - */ -SLV2_API -SLV2PluginClass -slv2_plugin_get_class(SLV2Plugin plugin); - -/** Get a value associated with the plugin in a plugin's data files. - * @a predicate must be either a URI or a QName. - * - * Returns the ?object of all triples found of the form: - * - * <code><plugin-uri> predicate ?object</code> - * - * May return NULL if the property was not found, or if object(s) is not - * sensibly represented as an SLV2Values (e.g. blank nodes). - * Return value must be freed by caller with slv2_values_free. - */ -SLV2_API -SLV2Values -slv2_plugin_get_value(SLV2Plugin p, - SLV2Value predicate); - -/** Get a value associated with the plugin in a plugin's data files. - * This function is identical to slv2_plugin_get_value, but takes a QName - * string parameter for a predicate instead of an SLV2Value, which may be - * more convenient. - */ -SLV2_API -SLV2Values -slv2_plugin_get_value_by_qname(SLV2Plugin p, - const char* predicate); - -/** Get a value associated with some subject in a plugin's data files. - * @a predicate must be either a URI or a QName. - * - * Returns the ?object of all triples found of the form: - * - * <code>subject predicate ?object</code> - * - * This can be used to investigate URIs returned by slv2_plugin_get_value - * (if information about it is contained in the plugin's data files). - * - * May return NULL if the property was not found, or if object is not - * sensibly represented as an SLV2Values (e.g. blank nodes). - * Return value must be freed by caller with slv2_values_free. - */ -SLV2_API -SLV2Values -slv2_plugin_get_value_for_subject(SLV2Plugin p, - SLV2Value subject_uri, - SLV2Value predicate_uri); - -/** Return whether a feature is supported by a plugin. - * This will return true if the feature is an optional or required feature - * of the plugin. - */ -SLV2_API -bool -slv2_plugin_has_feature(SLV2Plugin p, - SLV2Value feature_uri); - -/** Get the LV2 Features supported (required or optionally) by a plugin. - * A feature is "supported" by a plugin if it is required OR optional. - * - * Since required features have special rules the host must obey, this function - * probably shouldn't be used by normal hosts. Using slv2_plugin_get_optional_features - * and slv2_plugin_get_required_features separately is best in most cases. - * - * Returned value must be freed by caller with slv2_values_free. - */ -SLV2_API -SLV2Values -slv2_plugin_get_supported_features(SLV2Plugin p); - -/** Get the LV2 Features required by a plugin. - * If a feature is required by a plugin, hosts MUST NOT use the plugin if they do not - * understand (or are unable to support) that feature. - * - * All values returned here MUST be passed to the plugin's instantiate method - * (along with data, if necessary, as defined by the feature specification) - * or plugin instantiation will fail. - * - * Return value must be freed by caller with slv2_values_free. - */ -SLV2_API -SLV2Values -slv2_plugin_get_required_features(SLV2Plugin p); - -/** Get the LV2 Features optionally supported by a plugin. - * Hosts MAY ignore optional plugin features for whatever reasons. Plugins - * MUST operate (at least somewhat) if they are instantiated without being - * passed optional features. - * - * Return value must be freed by caller with slv2_values_free. - */ -SLV2_API -SLV2Values -slv2_plugin_get_optional_features(SLV2Plugin p); - -/** Get the number of ports on this plugin. - */ -SLV2_API -uint32_t -slv2_plugin_get_num_ports(SLV2Plugin p); - -/** Get the port ranges (minimum, maximum and default values) for all ports. - * @a min_values, @a max_values and @a def_values must either point to an array - * of N floats, where N is the value returned by slv2_plugin_get_num_ports() - * for this plugin, or NULL. The elements of the array will be set to the - * the minimum, maximum and default values of the ports on this plugin, - * with array index corresponding to port index. If a port doesn't have a - * minimum, maximum or default value, or the port's type is not float, the - * corresponding array element will be set to NAN. - * - * This is a convenience method for the common case of getting the range of - * all float ports on a plugin, and may be significantly faster than - * repeated calls to slv2_port_get_range. - */ -SLV2_API -void -slv2_plugin_get_port_ranges_float(SLV2Plugin p, - float* min_values, - float* max_values, - float* def_values); - -/** Get the number of ports on this plugin that are members of some class(es). - * Note that this is a varargs function so ports fitting any type 'profile' - * desired can be found quickly. REMEMBER TO TERMINATE THE PARAMETER LIST - * OF THIS FUNCTION WITH NULL OR VERY NASTY THINGS WILL HAPPEN. - */ -SLV2_API -uint32_t -slv2_plugin_get_num_ports_of_class(SLV2Plugin p, - SLV2Value class_1, ...); - -/** Return whether or not the plugin introduces (and reports) latency. - * The index of the latency port can be found with slv2_plugin_get_latency_port - * ONLY if this function returns true. - */ -SLV2_API -bool -slv2_plugin_has_latency(SLV2Plugin p); - -/** Return the index of the plugin's latency port. - * It is a fatal error to call this on a plugin without checking if the port - * exists by first calling slv2_plugin_has_latency. - * - * Any plugin that introduces unwanted latency that should be compensated for - * (by hosts with the ability/need) MUST provide this port, which is a control - * rate output port that reports the latency for each cycle in frames. - */ -SLV2_API -uint32_t -slv2_plugin_get_latency_port_index(SLV2Plugin p); - -/** Get a port on @a plugin by @a index. - */ -SLV2_API -SLV2Port -slv2_plugin_get_port_by_index(SLV2Plugin plugin, - uint32_t index); - -/** Get a port on @a plugin by @a symbol. - * Note this function is slower than slv2_plugin_get_port_by_index, - * especially on plugins with a very large number of ports. - */ -SLV2_API -SLV2Port -slv2_plugin_get_port_by_symbol(SLV2Plugin plugin, - SLV2Value symbol); - -/** Get a list of all UIs available for this plugin. - * Note this returns the URI of the UI, and not the path/URI to its shared - * library, use slv2_ui_get_library_uri with the values returned - * here for that. - * - * Returned value must be freed by caller using slv2_uis_free. - */ -SLV2_API -SLV2UIs -slv2_plugin_get_uis(SLV2Plugin plugin); - -/** Get the full name of the plugin's author. - * Returns NULL if author name is not present. - * Returned value must be freed by caller. - */ -SLV2_API -SLV2Value -slv2_plugin_get_author_name(SLV2Plugin plugin); - -/** Get the email address of the plugin's author. - * Returns NULL if author email address is not present. - * Returned value must be freed by caller. - */ -SLV2_API -SLV2Value -slv2_plugin_get_author_email(SLV2Plugin plugin); - -/** Get the email address of the plugin's author. - * Returns NULL if author homepage is not present. - * Returned value must be freed by caller. - */ -SLV2_API -SLV2Value -slv2_plugin_get_author_homepage(SLV2Plugin plugin); - -/** @} */ - -#ifdef __cplusplus -} /* extern "C" */ -#endif - -#endif /* __SLV2_PLUGIN_H__ */ - |