World¶

The “world” represents all Lilv state, and is used to discover/load/cache LV2 data (plugins, UIs, and extensions).

Normal hosts which just need to load plugins by URI should simply use lilv_world_load_all() to discover/load the system’s LV2 resources.

LilvWorld *lilv_world_new(void)¶

Initialize a new, empty world.

If initialization fails, NULL is returned.

void lilv_world_set_option(LilvWorld *world, const char *uri, const LilvNode *value)¶

Set an option for world.

Currently recognized options:

LILV_OPTION_FILTER_LANG
LILV_OPTION_DYN_MANIFEST
LILV_OPTION_LV2_PATH

void lilv_world_free(LilvWorld *world)¶

Destroy the world.

It is safe to call this function on NULL. Note that destroying world will destroy all the objects it contains. Do not destroy the world until you are finished with all objects that came from it.

void lilv_world_load_all(LilvWorld *world)¶

Load all installed LV2 bundles on the system.

This is the recommended way for hosts to load LV2 data. It implements the established/standard best practice for discovering all LV2 data on the system. The environment variable LV2_PATH may be used to control where this function will look for bundles.

Hosts should use this function rather than explicitly load bundles, except in special circumstances such as development utilities, or hosts that ship with special plugin bundles which are installed to a known location.

void lilv_world_load_bundle(LilvWorld *world, const LilvNode *bundle_uri)¶

Load a specific bundle.

bundle_uri must be a fully qualified URI to the bundle directory, with the trailing slash, eg. file:///usr/lib/lv2/foo.lv2/

Normal hosts should not need this function (use lilv_world_load_all()).

Hosts MUST NOT attach any long-term significance to bundle paths (for example in save files), since there are no guarantees they will remain unchanged between (or even during) program invocations. Plugins (among other things) MUST be identified by URIs (not paths) in save files.

void lilv_world_load_specifications(LilvWorld *world)¶

Load all specifications from currently loaded bundles.

This is for hosts that explicitly load specific bundles, its use is not necessary when using lilv_world_load_all(). This function parses the specifications and adds them to the model.

void lilv_world_load_plugin_classes(LilvWorld *world)¶

Load all plugin classes from currently loaded specifications.

Must be called after lilv_world_load_specifications(). This is for hosts that explicitly load specific bundles, its use is not necessary when using lilv_world_load_all().

int lilv_world_unload_bundle(LilvWorld *world, const LilvNode *bundle_uri)¶

Unload a specific bundle.

This unloads statements loaded by lilv_world_load_bundle(). Note that this is not necessarily all information loaded from the bundle. If any resources have been separately loaded with lilv_world_load_resource(), they must be separately unloaded with lilv_world_unload_resource().

int lilv_world_load_resource(LilvWorld *world, const LilvNode *resource)¶

Load all the data associated with the given resource.

All accessible data files linked to resource with rdfs:seeAlso will be loaded into the world model.

Parameters

world – The world.
resource – Must be a subject (a URI or a blank node).

Returns

The number of files parsed, or -1 on error

int lilv_world_unload_resource(LilvWorld *world, const LilvNode *resource)¶

Unload all the data associated with the given resource.

This unloads all data loaded by a previous call to lilv_world_load_resource() with the given resource.

Parameters

world – The world.
resource – Must be a subject (a URI or a blank node).

const LilvPluginClass *lilv_world_get_plugin_class(const LilvWorld *world)¶: Get the parent of all other plugin classes, lv2:Plugin.

const LilvPluginClasses *lilv_world_get_plugin_classes(const LilvWorld *world)¶

Return a list of all found plugin classes.

Returned list is owned by world and must not be freed by the caller.

const LilvPlugins *lilv_world_get_all_plugins(const LilvWorld *world)¶

Return a list of all found plugins.

The returned list contains just enough references to query or instantiate plugins. The data for a particular plugin will not be loaded into memory until a call to an lilv_plugin_* function results in a query (at which time the data is cached with the LilvPlugin so future queries are very fast).

The returned list and the plugins it contains are owned by world and must not be freed by caller.

LilvNodes *lilv_world_find_nodes(LilvWorld *world, const LilvNode *subject, const LilvNode *predicate, const LilvNode *object)¶

Find nodes matching a triple pattern.

Either subject or object may be NULL (a wildcard), but not both.

Returns: All matches for the wildcard field, or NULL.

LilvNode *lilv_world_get(LilvWorld *world, const LilvNode *subject, const LilvNode *predicate, const LilvNode *object)¶

Find a single node that matches a pattern.

Exactly one of subject, predicate, object must be NULL. This function is equivalent to lilv_nodes_get_first(lilv_world_find_nodes(…)) but simplifies the common case of only wanting a single value.

Returns: The first matching node, or NULL if no matches are found.

bool lilv_world_ask(LilvWorld *world, const LilvNode *subject, const LilvNode *predicate, const LilvNode *object)¶

Return true iff a statement matching a certain pattern exists.

This is useful for checking if particular statement exists without having to bother with collections and memory management.

Parameters

world – The world.
subject – Subject of statement, or NULL for anything.
predicate – Predicate (key) of statement, or NULL for anything.
object – Object (value) of statement, or NULL for anything.

LilvNode *lilv_world_get_symbol(LilvWorld *world, const LilvNode *subject)¶

Get an LV2 symbol for some subject.

This will return the lv2:symbol property of the subject if it is given explicitly, and otherwise will attempt to derive a symbol from the URI.

Returns: A string node that is a valid LV2 symbol, or NULL on error.

LILV_OPTION_FILTER_LANG¶

Enable/disable language filtering.

Language filtering applies to any functions that return (a) value(s). With filtering enabled, Lilv will automatically return the best value(s) for the current LANG. With filtering disabled, all matching values will be returned regardless of language tag. Filtering is enabled by default.

LILV_OPTION_DYN_MANIFEST¶

Enable/disable dynamic manifest support.

Dynamic manifest data will only be loaded if this option is true.

LILV_OPTION_LV2_PATH¶

Set application-specific LV2_PATH.

This overrides the LV2_PATH from the environment, so that lilv will only look inside the given path. This can be used to make self-contained applications.