diff options
Diffstat (limited to 'slv2/plugin.h')
| -rw-r--r-- | slv2/plugin.h | 155 |
1 files changed, 20 insertions, 135 deletions
diff --git a/slv2/plugin.h b/slv2/plugin.h index e936bf4..f688626 100644 --- a/slv2/plugin.h +++ b/slv2/plugin.h @@ -29,7 +29,7 @@ extern "C" { #include "slv2/port.h" #include "slv2/collections.h" -/** \defgroup slv2_data Plugin data access +/** @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. @@ -42,25 +42,19 @@ extern "C" { */ /** Check if this plugin is valid. - * - * This is used by plugin lists to avoid loading plugins that are not valid - * and will not work with libslv2 (eg plugins missing required fields, or - * having multiple values for mandatory single-valued fields, etc. + * 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 if \a plugin is valid. - * - * Time = Query + * @return true iff @a plugin is valid. */ SLV2_API bool slv2_plugin_verify(SLV2Plugin plugin); -/** Get the URI of \a 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. @@ -71,70 +65,51 @@ slv2_plugin_verify(SLV2Plugin 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 string which must not be modified or free()'d. - * - * Time = O(1) + * @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 plugins "main" bundle. - * +/** 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 returns URIs which are not below this one. + * 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. - * - * Time = O(1) + * @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", + * @return a list of complete URLs eg. "file:///foo/ABundle.lv2/aplug.ttl", * which is shared and must not be modified or freed. - * - * Time = O(1) */ SLV2_API SLV2Values slv2_plugin_get_data_uris(SLV2Plugin plugin); -/** Get the (resolvable) URI of the shared library for \a 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. - * - * Time = O(1) + * @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. - * +/** 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. - * - * Time = Query */ SLV2_API SLV2Value @@ -147,6 +122,7 @@ 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: * @@ -154,13 +130,7 @@ slv2_plugin_get_class(SLV2Plugin plugin); * * 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. - * - * \a predicate must be either a URI or a QName. - * See SLV2URIType documentation for examples. - * - * Time = Query */ SLV2_API SLV2Values @@ -168,7 +138,6 @@ 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. @@ -179,6 +148,7 @@ 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: * @@ -189,13 +159,7 @@ slv2_plugin_get_value_by_qname(SLV2Plugin p, * * May return NULL if the property was not found, or if object is not * sensibly represented as an SLV2Values (e.g. blank nodes). - * - * \a predicate must be either a URI or a QName. - * See SLV2URIType documentation for examples. - * * Return value must be freed by caller with slv2_values_free. - * - * Time = Query */ SLV2_API SLV2Values @@ -204,11 +168,8 @@ slv2_plugin_get_value_for_subject(SLV2Plugin p, 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. - * - * Time = Query */ SLV2_API bool @@ -216,7 +177,6 @@ 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 @@ -224,15 +184,12 @@ slv2_plugin_has_feature(SLV2Plugin p, * and slv2_plugin_get_required_features separately is best in most cases. * * Returned value must be freed by caller with slv2_values_free. - * - * Time = Query */ 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. * @@ -241,38 +198,30 @@ slv2_plugin_get_supported_features(SLV2Plugin p); * or plugin instantiation will fail. * * Return value must be freed by caller with slv2_values_free. - * - * Time = Query */ 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. - * - * Time = Query */ SLV2_API SLV2Values slv2_plugin_get_optional_features(SLV2Plugin p); /** Get the number of ports on this plugin. - * - * Time = O(1) */ 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 + * @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, @@ -292,12 +241,9 @@ slv2_plugin_get_port_ranges_float(SLV2Plugin p, 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. - * - * Time = O(1) */ SLV2_API uint32_t @@ -305,82 +251,35 @@ 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. - * - * Time = Query */ 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. - * - * Time = Query */ SLV2_API uint32_t slv2_plugin_get_latency_port_index(SLV2Plugin p); -/** Query a plugin for a single variable (i.e. SELECT a single ?value). - * - * \param plugin The plugin to query. - * \param sparql_str A SPARQL SELECT query. - * \param variable The index of the variable to return results for - * (e.g. with "<code>SELECT ?foo ?bar</code>" foo=0, bar=1). - * \return All matches for \a variable. - * - * Time = Query - */ -SLV2_API -SLV2Values -slv2_plugin_query_variable(SLV2Plugin plugin, - const char* sparql_str, - unsigned variable); - -/** Query a plugin and return the number of results found. - * - * Note that this function will work, but is mostly meaningless for queries - * that are not SELECT DISTINCT. - * - * \param plugin The plugin to query. - * \param sparql_str A SPARQL SELECT DISTINCT query. - * - * Time = Query - */ -SLV2_API -unsigned -slv2_plugin_query_count(SLV2Plugin plugin, - const char* sparql_str); - -/** Get a port on this plugin by \a index. - * - * To perform multiple calls on a port, the returned value should - * be cached and used repeatedly. - * - * Time = O(1) +/** 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 this plugin by \a symbol. - * - * To perform multiple calls on a port, the returned value should - * be cached and used repeatedly. Note this function is slower - * than slv2_plugin_get_port_by_index, especially on plugins - * with a very large number of ports. - * - * Time = O(n) +/** 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 @@ -388,49 +287,35 @@ 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. - * - * \param plugin The plugin to get the UIs for. - * - * Time = Query */ 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. - * - * Time = Query */ 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. - * - * Time = Query */ 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. - * - * Time = Query */ SLV2_API SLV2Value |