slv2_data (3) - Linux Manuals
NAME
Plugin data access -
Functions
bool slv2_plugin_verify (SLV2Plugin plugin)
SLV2Value slv2_plugin_get_uri (SLV2Plugin plugin)
SLV2Value slv2_plugin_get_bundle_uri (SLV2Plugin plugin)
SLV2Values slv2_plugin_get_data_uris (SLV2Plugin plugin)
SLV2Value slv2_plugin_get_library_uri (SLV2Plugin plugin)
SLV2Value slv2_plugin_get_name (SLV2Plugin plugin)
SLV2Values slv2_plugin_get_value (SLV2Plugin p, SLV2Value predicate)
SLV2Values slv2_plugin_get_value_by_qname (SLV2Plugin p, const char *predicate)
SLV2Values slv2_plugin_get_value_by_qname_i18n (SLV2Plugin p, const char *predicate)
SLV2Values slv2_plugin_get_value_for_subject (SLV2Plugin p, SLV2Value subject_uri, SLV2Value predicate_uri)
bool slv2_plugin_has_feature (SLV2Plugin p, SLV2Value feature_uri)
SLV2Values slv2_plugin_get_supported_features (SLV2Plugin p)
SLV2Values slv2_plugin_get_required_features (SLV2Plugin p)
SLV2Values slv2_plugin_get_optional_features (SLV2Plugin p)
uint32_t slv2_plugin_get_num_ports (SLV2Plugin p)
void slv2_plugin_get_port_ranges_float (SLV2Plugin p, float *min_values, float *max_values, float *def_values)
uint32_t slv2_plugin_get_num_ports_of_class (SLV2Plugin p, SLV2Value class_1,...)
bool slv2_plugin_has_latency (SLV2Plugin p)
uint32_t slv2_plugin_get_latency_port_index (SLV2Plugin p)
SLV2Values slv2_plugin_query_variable (SLV2Plugin plugin, const char *sparql_str, unsigned variable)
unsigned slv2_plugin_query_count (SLV2Plugin plugin, const char *sparql_str)
SLV2Port slv2_plugin_get_port_by_index (SLV2Plugin plugin, uint32_t index)
SLV2Port slv2_plugin_get_port_by_symbol (SLV2Plugin plugin, SLV2Value symbol)
SLV2UIs slv2_plugin_get_uis (SLV2Plugin plugin)
SLV2Value slv2_plugin_get_author_name (SLV2Plugin plugin)
SLV2Value slv2_plugin_get_author_email (SLV2Plugin plugin)
SLV2Value slv2_plugin_get_author_homepage (SLV2Plugin plugin)
SLV2Value slv2_plugin_class_get_parent_uri (SLV2PluginClass plugin_class)
SLV2Value slv2_plugin_class_get_uri (SLV2PluginClass plugin_class)
SLV2Value slv2_plugin_class_get_label (SLV2PluginClass plugin_class)
SLV2PluginClasses slv2_plugin_class_get_children (SLV2PluginClass plugin_class)
SLV2Value slv2_ui_get_uri (SLV2UI ui)
SLV2Values slv2_ui_get_classes (SLV2UI ui)
bool slv2_ui_is_a (SLV2UI ui, SLV2Value class_uri)
SLV2Value slv2_ui_get_bundle_uri (SLV2UI ui)
SLV2Value slv2_ui_get_binary_uri (SLV2UI ui)
SLV2Values slv2_port_get_value (SLV2Plugin plugin, SLV2Port port, SLV2Value predicate)
SLV2Values slv2_port_get_value_by_qname (SLV2Plugin plugin, SLV2Port port, const char *property_uri)
SLV2Values slv2_port_get_value_by_qname_i18n (SLV2Plugin plugin, SLV2Port port, const char *property_uri)
SLV2Values slv2_port_get_properties (SLV2Plugin plugin, SLV2Port port)
bool slv2_port_has_property (SLV2Plugin p, SLV2Port port, SLV2Value property_uri)
bool slv2_port_supports_event (SLV2Plugin p, SLV2Port port, SLV2Value event_uri)
SLV2Value slv2_port_get_symbol (SLV2Plugin plugin, SLV2Port port)
SLV2Value slv2_port_get_name (SLV2Plugin plugin, SLV2Port port)
SLV2Values slv2_port_get_classes (SLV2Plugin plugin, SLV2Port port)
bool slv2_port_is_a (SLV2Plugin plugin, SLV2Port port, SLV2Value port_class)
void slv2_port_get_range (SLV2Plugin plugin, SLV2Port port, SLV2Value *def, SLV2Value *min, SLV2Value *max)
SLV2ScalePoints slv2_port_get_scale_points (SLV2Plugin plugin, SLV2Port port)
unsigned slv2_results_size (SLV2Results results)
SLV2Value slv2_results_get_binding_value (SLV2Results results, unsigned index)
SLV2Value slv2_results_get_binding_value_by_name (SLV2Results results, const char *name)
const char * slv2_results_get_binding_name (SLV2Results results, unsigned index)
SLV2Value slv2_scale_point_get_label (SLV2ScalePoint point)
SLV2Value slv2_scale_point_get_value (SLV2ScalePoint point)
SLV2Value slv2_value_new_uri (SLV2World world, const char *uri)
SLV2Value slv2_value_new_string (SLV2World world, const char *str)
SLV2Value slv2_value_new_int (SLV2World world, int val)
SLV2Value slv2_value_new_float (SLV2World world, float val)
char * slv2_value_get_turtle_token (SLV2Value value)
bool slv2_value_is_uri (SLV2Value value)
const char * slv2_value_as_uri (SLV2Value value)
bool slv2_value_is_literal (SLV2Value value)
bool slv2_value_is_string (SLV2Value value)
const char * slv2_value_as_string (SLV2Value value)
bool slv2_value_is_float (SLV2Value value)
float slv2_value_as_float (SLV2Value value)
bool slv2_value_is_int (SLV2Value value)
int slv2_value_as_int (SLV2Value value)
Detailed Description
An SLV2Plugin contains an in-memory cache of the plugin data, loaded on demand. Duplicating plugins should be avoided when possible for performance reasons.
Function Documentation
bool slv2_plugin_verify (SLV2Pluginplugin)
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.
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.
Returns:
- true if plugin is valid.
SLV2Value slv2_plugin_get_uri (SLV2Pluginplugin)
Get the URI of 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.
Returns:
- a shared string which must not be modified or free()'d.
Time = O(1)
SLV2Value slv2_plugin_get_bundle_uri (SLV2Pluginplugin)
Get the (resolvable) URI of the plugins '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.
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.
Returns:
- a shared string which must not be modified or freed.
Time = O(1)
SLV2Values slv2_plugin_get_data_uris (SLV2Pluginplugin)
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.
Returns:
- 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)
SLV2Value slv2_plugin_get_library_uri (SLV2Pluginplugin)
Get the (resolvable) URI of the shared library for plugin. Note this always returns a fully qualified URI. If you want a local filesystem path, use slv2_uri_to_path.
Returns:
- a shared string which must not be modified or freed.
Time = O(1)
SLV2Value slv2_plugin_get_name (SLV2Pluginplugin)
Get the name of plugin. This is guaranteed to return the untranslated name (the doap:name in the data file without a language tag). Returned value must be freed by the caller.
SLV2Values slv2_plugin_get_value (SLV2Pluginp, SLV2Valuepredicate)
Get a value associated with the plugin in a plugin's data files. Returns the ?object of all triples found of the form:
<plugin-uri> predicate ?object
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.
predicate must be either a URI or a QName. See SLV2URIType documentation for examples.
SLV2Values slv2_plugin_get_value_by_qname (SLV2Pluginp, const char *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.
SLV2Values slv2_plugin_get_value_by_qname_i18n (SLV2Pluginp, const char *predicate)
Get a translated 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. It returns the value translated to the current language if possible.
SLV2Values slv2_plugin_get_value_for_subject (SLV2Pluginp, SLV2Valuesubject_uri, SLV2Valuepredicate_uri)
Get a value associated with some subject in a plugin's data files. Returns the ?object of all triples found of the form:
subject predicate ?object
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).
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.
bool slv2_plugin_has_feature (SLV2Pluginp, SLV2Valuefeature_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.
SLV2Values slv2_plugin_get_supported_features (SLV2Pluginp)
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.
SLV2Values slv2_plugin_get_required_features (SLV2Pluginp)
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.
SLV2Values slv2_plugin_get_optional_features (SLV2Pluginp)
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.
uint32_t slv2_plugin_get_num_ports (SLV2Pluginp)
Get the number of ports on this plugin. Time = O(1)
void slv2_plugin_get_port_ranges_float (SLV2Pluginp, float *min_values, float *max_values, float *def_values)
Get the port ranges (minimum, maximum and default values) for all ports. min_values, max_values and 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.
uint32_t slv2_plugin_get_num_ports_of_class (SLV2Pluginp, SLV2Valueclass_1, ...)
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)
bool slv2_plugin_has_latency (SLV2Pluginp)
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.
uint32_t slv2_plugin_get_latency_port_index (SLV2Pluginp)
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.
SLV2Values slv2_plugin_query_variable (SLV2Pluginplugin, const char *sparql_str, unsignedvariable)
Query a plugin for a single variable (i.e. SELECT a single ?value).
Parameters:
-
plugin The plugin to query.
sparql_str A SPARQL SELECT query.
variable The index of the variable to return results for (e.g. with '<code>SELECT ?foo ?bar</code>' foo=0, bar=1).
Returns:
- All matches for variable.
unsigned slv2_plugin_query_count (SLV2Pluginplugin, const char *sparql_str)
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.
Parameters:
-
plugin The plugin to query.
sparql_str A SPARQL SELECT DISTINCT query.
SLV2Port slv2_plugin_get_port_by_index (SLV2Pluginplugin, uint32_tindex)
Get a port on this plugin by index. To perform multiple calls on a port, the returned value should be cached and used repeatedly.
Time = O(1)
SLV2Port slv2_plugin_get_port_by_symbol (SLV2Pluginplugin, SLV2Valuesymbol)
Get a port on this plugin by 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)
SLV2UIs slv2_plugin_get_uis (SLV2Pluginplugin)
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.
Parameters:
- plugin The plugin to get the UIs for.
SLV2Value slv2_plugin_get_author_name (SLV2Pluginplugin)
Get the full name of the plugin's author. Returns NULL if author name is not present. Returned value must be freed by caller.
SLV2Value slv2_plugin_get_author_email (SLV2Pluginplugin)
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.
SLV2Value slv2_plugin_get_author_homepage (SLV2Pluginplugin)
Get the email address of the plugin's author. Returns NULL if author homepage is not present. Returned value must be freed by caller.
SLV2Value slv2_plugin_class_get_parent_uri (SLV2PluginClassplugin_class)
Get the URI of this class' superclass. Returned value is owned by plugin_class and must not be freed by caller. Returned value may be NULL, if class has no parent.
Time = O(1)
SLV2Value slv2_plugin_class_get_uri (SLV2PluginClassplugin_class)
Get the URI of this plugin class. Returned value is owned by plugin_class and must not be freed by caller.
Time = O(1)
SLV2Value slv2_plugin_class_get_label (SLV2PluginClassplugin_class)
Get the label of this plugin class, ie 'Oscillators'. Returned value is owned by plugin_class and must not be freed by caller.
Time = O(1)
SLV2PluginClasses slv2_plugin_class_get_children (SLV2PluginClassplugin_class)
Get the subclasses of this plugin class. Returned value must be freed by caller with slv2_plugin_classes_free.
SLV2Value slv2_ui_get_uri (SLV2UIui)
Get the URI of a Plugin UI.
Parameters:
- ui The Plugin UI
Returns:
- a shared value which must not be modified or freed.
Time = O(1)
SLV2Values slv2_ui_get_classes (SLV2UIui)
Get the types (URIs of RDF classes) of a Plugin UI.
Parameters:
- ui The Plugin UI
Returns:
- a shared value which must not be modified or freed.
Time = O(1)
bool slv2_ui_is_a (SLV2UIui, SLV2Valueclass_uri)
Check whether a plugin UI is a given type.
Parameters:
-
ui The Plugin UI
class_uri The URI of the LV2 UI type to check this UI against
Time = O(1)
SLV2Value slv2_ui_get_bundle_uri (SLV2UIui)
Get the URI for a Plugin UI's bundle.
Parameters:
- ui The Plugin UI
Returns:
- a shared value which must not be modified or freed.
Time = O(1)
SLV2Value slv2_ui_get_binary_uri (SLV2UIui)
Get the URI for a Plugin UI's shared library.
Parameters:
- ui The Plugin UI
Returns:
- a shared value which must not be modified or freed.
Time = O(1)
SLV2Values slv2_port_get_value (SLV2Pluginplugin, SLV2Portport, SLV2Valuepredicate)
Port analog of slv2_plugin_get_value. Time = Query
SLV2Values slv2_port_get_value_by_qname (SLV2Pluginplugin, SLV2Portport, const char *property_uri)
Port analog of slv2_plugin_get_value_by_qname. Time = Query
SLV2Values slv2_port_get_value_by_qname_i18n (SLV2Pluginplugin, SLV2Portport, const char *property_uri)
Port analog of slv2_plugin_get_value_by_qname_i18n. Time = Query
SLV2Values slv2_port_get_properties (SLV2Pluginplugin, SLV2Portport)
Return the LV2 port properties of a port. Time = Query
bool slv2_port_has_property (SLV2Pluginp, SLV2Portport, SLV2Valueproperty_uri)
Return whether a port has a certain property. Time = Query
bool slv2_port_supports_event (SLV2Pluginp, SLV2Portport, SLV2Valueevent_uri)
Return whether a port is an event port and supports a certain event type. Time = Query
SLV2Value slv2_port_get_symbol (SLV2Pluginplugin, SLV2Portport)
Get the symbol of a port. The 'symbol' is a short string, a valid C identifier. Returned value is owned by port and must not be freed.
SLV2Value slv2_port_get_name (SLV2Pluginplugin, SLV2Portport)
Get the name of a port. This is guaranteed to return the untranslated name (the doap:name in the data file without a language tag). Returned value must be freed by the caller.
SLV2Values slv2_port_get_classes (SLV2Pluginplugin, SLV2Portport)
Get all the classes of a port. This can be used to determine if a port is an input, output, audio, control, midi, etc, etc, though it's simpler to use slv2_port_is_a. The returned list does not include lv2:Port, which is implied.
Returned value is shared and must not be destroyed by caller.
Time = O(1)
bool slv2_port_is_a (SLV2Pluginplugin, SLV2Portport, SLV2Valueport_class)
Determine if a port is of a given class (input, output, audio, etc). For convenience/performance/extensibility reasons, hosts are expected to create an SLV2Value for each port class they 'care about'. Well-known type URI strings are defined (e.g. SLV2_PORT_CLASS_INPUT) for convenience, but this function is designed so that SLV2 is usable with any port types without requiring explicit support in SLV2.
Time = O(n) (n pointer comparisons where n is the number of classes of this port, so this method is suitable for realtime use on any sane port).
void slv2_port_get_range (SLV2Pluginplugin, SLV2Portport, SLV2Value *def, SLV2Value *min, SLV2Value *max)
Get the default, minimum, and maximum values of a port. def, min, and max are outputs, pass pointers to uninitialized (i.e. NOT created with slv2_value_new) SLV2Value variables. These will be set to point at new values (which must be freed by the caller using slv2_value_free), or NULL if the value does not exist.
SLV2ScalePoints slv2_port_get_scale_points (SLV2Pluginplugin, SLV2Portport)
Get the scale points (enumeration values) of a port. This returns a collection of 'interesting' named values of a port (e.g. appropriate entries for a UI selector associated with this port).
Returned value may be NULL if port has no scale points, otherwise it must be freed by caller with slv2_scale_points_free.
unsigned slv2_results_size (SLV2Resultsresults)
Return the number of matches in results. Note this should not be used to iterate over a result set (since it will iterate to the end of results and rewinding is impossible). Instead, use slv2_results_next and slv2_results_finished repeatedly.
SLV2Value slv2_results_get_binding_value (SLV2Resultsresults, unsignedindex)
Return a binding in results by index. Indices correspond to selected variables in the query in order of appearance. Returned value must be freed by caller with slv2_value_free.
Returns:
- NULL if binding value can not be expressed as an SLV2Value.
SLV2Value slv2_results_get_binding_value_by_name (SLV2Resultsresults, const char *name)
Return a binding in results by name. name corresponds to the name of the SPARQL variable (without the '?'). Returned value must be freed by caller with slv2_value_free.
Returns:
- NULL if binding value can not be expressed as an SLV2Value.
const char* slv2_results_get_binding_name (SLV2Resultsresults, unsignedindex)
Return the name of a binding in results. Returned value is shared and must not be freed by caller. Indices correspond to selected variables in the query in order of appearance.
SLV2Value slv2_scale_point_get_label (SLV2ScalePointpoint)
Get the label of this scale point (enumeration value) Returned value is owned by point and must not be freed.
SLV2Value slv2_scale_point_get_value (SLV2ScalePointpoint)
Get the value of this scale point (enumeration value) Returned value is owned by point and must not be freed.
SLV2Value slv2_value_new_uri (SLV2Worldworld, const char *uri)
Create a new URI value. Returned value must be freed by caller with slv2_value_free.
SLV2Value slv2_value_new_string (SLV2Worldworld, const char *str)
Create a new string value (with no language). Returned value must be freed by caller with slv2_value_free.
SLV2Value slv2_value_new_int (SLV2Worldworld, intval)
Create a new integer value. Returned value must be freed by caller with slv2_value_free.
SLV2Value slv2_value_new_float (SLV2Worldworld, floatval)
Create a new floating point value. Returned value must be freed by caller with slv2_value_free.
char* slv2_value_get_turtle_token (SLV2Valuevalue)
Return this value as a Turtle/SPARQL token. Examples: http://example.org/foo doap:name 'this is a string' 1.0 1
Returned string is newly allocated and must be freed by caller.
bool slv2_value_is_uri (SLV2Valuevalue)
Return whether the value is a URI (resource). Time = O(1)
const char* slv2_value_as_uri (SLV2Valuevalue)
Return this value as a URI string, e.g. 'http://example.org/foo'.
Valid to call only if slv2_value_is_uri(value) returns true. Returned value is owned by value and must not be freed by caller.
Time = O(1)
bool slv2_value_is_literal (SLV2Valuevalue)
Return whether this value is a literal (i.e. not a URI).
Returns true if value is a string or numeric value.
Time = O(1)
bool slv2_value_is_string (SLV2Valuevalue)
Return whether this value is a string literal. Returns true if value is a string (but not numeric) value.
Time = O(1)
const char* slv2_value_as_string (SLV2Valuevalue)
Return value as a string. Time = O(1)
bool slv2_value_is_float (SLV2Valuevalue)
Return whether this value is a decimal literal. Time = O(1)
float slv2_value_as_float (SLV2Valuevalue)
Return value as a float. Valid to call only if slv2_value_is_float(value) or slv2_value_is_int(value) returns true.
Time = O(1)
bool slv2_value_is_int (SLV2Valuevalue)
Return whether this value is an integer literal. Time = O(1)
int slv2_value_as_int (SLV2Valuevalue)
Return value as an integer. Valid to call only if slv2_value_is_int(value) returns true.
Time = O(1)
Author
Generated automatically by Doxygen for SLV2 from the source code.