Struct PluginEntry 

pub struct PluginEntry { /* private fields */ }

A handle to a loaded CLAP plugin entry.

This allows getting all the factories exposed by the entry, mainly the PluginFactory which allows to list plugin instances.

This is only a lightweight handle: plugin entries are only loaded once, and the Clone operation on this type only clones the handle.

Plugin entries are only unloaded when all handles are dropped and all associated instances are unloaded.

A PluginEntry can also be loaded from a static EntryDescriptor instead of a file. See PluginEntry::load_from_raw.

See the module docs for more information about CLAP entries.

Example

use clack_host::prelude::PluginEntry;

let entry = unsafe { PluginEntry::load("/home/user/.clap/u-he/libdiva.so")? };
let plugin_factory = entry.get_plugin_factory().unwrap();

println!("Loaded entry CLAP version: {}", entry.version());

Implementations

impl PluginEntry

pub unsafe fn load<P: AsRef<OsStr>>(path: P) -> Result<Self, PluginEntryError>

Available on crate feature libloading only.

Loads and initializes a CLAP entry from a dynamic library file located at the given path.

This function also initializes the loaded entry, using the provided path, and returns a handle to it.

If you wish to initialize the entry with a different path than the one of the dynamic library file it comes from, you can use load_from with a LibraryEntry as an argument.

Platform compatibility notes

On macOS, plugins are not packaged as their dynamic library file directly, but as a standard bundle which contains the dynamic library file instead.

For convenience, on macOS this function can accept both a path to the plugin bundle, or a path to the dynamic library file itself.

If a path to a bundle is given to this function, it will use its Info.plist file to locate the bundle’s executable and load that. It will then use the given path to the bundle to initialize the entry.

If a path to a file is given to this function, it will load that as the dynamic library file, and attempt to find or reconstruct the bundle’s path from the executable path. It will then use that path to initialize the entry.

If you have access to both paths and want to eliminate this guesswork, you should use load_from with a LibraryEntry as an argument instead.

Safety

This function loads an external library object file, which is inherently unsafe, as even just loading it can trigger any behavior in your application, including Undefined Behavior.

Additionally, loading a non-compliant CLAP entry may invalidate safety assumptions other APIs in this library rely on. See the module docs’s Safety section for more information.

Errors

This method returns an error if loading the entry fails. See PluginEntryError for all the possible errors that may occur.

Example

use clack_host::prelude::PluginEntry;

let entry = unsafe { PluginEntry::load("/home/user/.clap/u-he/libdiva.so")? };

println!("Loaded entry CLAP version: {}", entry.version());

pub unsafe fn load_from( provider: impl EntryProvider, path: &CStr, ) -> Result<Self, PluginEntryError>

Initializes a CLAP entry exposed by the given EntryProvider.

This takes ownership of the given provider, and will keep it alive as long as there are PluginEntry references to it, or as long as PluginInstances (or other similar objects) created by this entry also exist.

Safety

Loading a non-compliant CLAP entry may invalidate safety assumptions other APIs in this library rely on. See the module docs’s Safety section for more information.

Errors

This method returns an error if initializing the entry fails. See PluginEntryError for all the possible errors that may occur.

pub fn load_from_clack<E: Entry>(path: &CStr) -> Result<Self, PluginEntryError>

Available on crate feature clack-plugin only.

Loads a CLAP entry from an Entry created by clack_plugin.

Note that CLAP plugins loaded this way still need a valid path to initialize, as they may perform various filesystem operations relative to their entry files.

Note that unlike other methods to load PluginEntrys, this method is completely safe, as it can rely on the safety guarantees provided by clack_plugin.

Errors

This method returns an error if initializing the entry fails. See PluginEntryError for all the possible errors that may occur.

pub unsafe fn load_from_raw( inner: &'static EntryDescriptor, plugin_path: &CStr, ) -> Result<Self, PluginEntryError>

Loads a CLAP entry from a 'static EntryDescriptor.

Note that CLAP plugins loaded this way still need a valid path, as they may perform various filesystem operations relative to their entry files.

Safety

Loading a non-compliant CLAP entry may invalidate safety assumptions other APIs in this library rely on. See the module docs’s Safety section for more information.

Errors

This method returns an error if initializing the entry fails. See PluginEntryError for all the possible errors that may occur.

Example

use clack_host::entry::EntryDescriptor;
use clack_host::prelude::PluginEntry;

let descriptor: &'static EntryDescriptor = /* ... */

let path = c"/home/user/.clap/u-he/libdiva.so";
let entry = unsafe { PluginEntry::load_from_raw(descriptor, path)? };

println!("Loaded entry CLAP version: {}", entry.version());

pub fn raw_entry(&self) -> &EntryDescriptor

Gets the raw, C-FFI plugin entry descriptor exposed by this entry.

pub fn get_factory<'a, F: Factory<'a>>(&'a self) -> Option<F>

Returns the Factory of type F exposed by this entry, if it exists.

If this entry does not expose a factory of the requested type, None is returned.

If you are looking to fetch the entry’s PluginFactory, you can also use the get_plugin_factory method, which is just a convenience wrapper around this method.

Example

use clack_host::factory::plugin::PluginFactory;
use clack_host::prelude::PluginEntry;

let entry = unsafe { PluginEntry::load("/home/user/.clap/u-he/libdiva.so")? };
let plugin_factory = entry.get_factory::<PluginFactory>().unwrap();

println!("Found {} plugins.", plugin_factory.plugin_count());

pub fn get_plugin_factory(&self) -> Option<PluginFactory<'_>>

Returns the PluginFactory exposed by this entry, if it exists.

If this entry does not expose a PluginFactory, None is returned.

This is a convenience method, and is equivalent to calling get_factory with a PluginFactory type parameter.

Example

use clack_host::prelude::PluginEntry;

let entry = unsafe { PluginEntry::load("/home/user/.clap/u-he/libdiva.so")? };
let plugin_factory = entry.get_plugin_factory().unwrap();

println!("Found {} plugins.", plugin_factory.plugin_count());

pub fn version(&self) -> ClapVersion

Returns the CLAP version used by this entry.

Trait Implementations

impl Clone for PluginEntry

fn clone(&self) -> PluginEntry

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.