Struct PluginDescriptor 

pub struct PluginDescriptor { /* private fields */ }

Provides metadata about a given Plugin, such as its ID, name, version, and more.

All fields of this type as exposed as optional, however the CLAP specification requires the id and name fields to be present. It is acceptable for a host to refuse loading a plugin that returns None for these fields.

As such, when constructing this type, the id and name fields are mandatory, and should not be blank. All the other fields are completely optional.

Note that all the read accessors of this type are exposed as the CLAP-native CStr, as they are not required by the CLAP spec to be UTF-8 compliant, only exposing byte slices. Hosts are left to interpret non-UTF-8 data best they can.

The write accessors on this type take string references for convenience reasons, but they will still internally convert them into null-terminated C strings, and panic if that conversion fails.

See the documentation each accessor method to learn about the available metadata.

Example

use clack_common::plugin::PluginDescriptor;

fn get_descriptor() -> PluginDescriptor {
  use clack_common::plugin::features::*;

  PluginDescriptor::new("org.rust-audio.clack.gain", "Clack Gain Example")
    .with_description("A simple gain plugin example!")
    .with_version("0.1.0")
    .with_features([AUDIO_EFFECT, STEREO])
}

Implementations

impl PluginDescriptor

pub fn new(id: &str, name: &str) -> Self

Creates a new plugin descriptor, initializing it with the given Plugin ID and name.

See the documentation of the id and name methods for more information about the id and name parameters.

Panics

This function will panic if either the given ID or name are empty strings.

This function will also panic if either the given ID or name contain invalid NULL-byte characters, which are invalid.

pub const unsafe fn from_raw(raw: &clap_plugin_descriptor) -> &Self

Creates a PluginDescriptor reference from a pointer to a raw, C-FFI compatible CLAP descriptor structure.

Safety

All fields must either be null, or point to a valid for reads, null-terminated C string (or for features, a null-terminated array of null-terminated C strings), which all must also be valid for reads for the lifetime of the resulting PluginDescriptor reference.

pub fn as_raw(&self) -> &clap_plugin_descriptor

Returns the plugin descriptor as a reference to the C-FFI compatible CLAP struct.

pub fn id(&self) -> Option<&CStr>

The unique identifier of a plugin.

This field is mandatory, and should not be blank. If it is found to be None, it is acceptable for the host to refuse to load this plugin.

This identifier should be as globally-unique as possible to any users that might load this plugin, as this is the key hosts will use to differentiate between different plugins.

Example: com.u-he.diva.

This method will return None if this is either missing or a blank (i.e. empty) string.

pub fn with_id(self, id: &str) -> Self

Sets the plugin’s unique ID.

See the id method documentation for more information.

Panics

This function will panic if the given ID is an empty string.

This function will also panic if the given ID contains NULL-byte characters, which are invalid.

pub fn name(&self) -> Option<&CStr>

The user-facing display name of this plugin.

This field is mandatory, and should not be blank. If it is found to be None, it is acceptable for the host to refuse to load this plugin.

This name will be displayed in plugin lists and selectors, and will be the main way users will find and differentiate the plugin.

Example: Diva.

This method will return None if this is either missing or a blank (i.e. empty) string.

pub fn with_name(self, name: &str) -> Self

Sets the plugin’s name.

See the name method documentation for more information.

Panics

This function will panic if the given name is an empty string.

This function will also panic if the given name contains NULL-byte characters, which are invalid.

pub fn vendor(&self) -> Option<&CStr>

The vendor of the plugin.

Example: u-he.

This method will return None if this is either missing or a blank (i.e. empty) string.

pub fn with_vendor(self, vendor: &str) -> Self

Sets the plugin’s vendor name.

See the vendor method documentation for more information.

Passing an empty string as the vendor parameter will mark it as unset, making vendor then return None.

Panics

This function will also panic if the given vendor name contains NULL-byte characters, which are invalid.

pub fn url(&self) -> Option<&CStr>

The URL of this plugin’s homepage.

Example: https://u-he.com/products/diva/.

This method will return None if this is either missing or a blank (i.e. empty) string.

pub fn with_url(self, url: &str) -> Self

Sets the plugin’s homepage’s URL.

See the url method documentation for more information.

Passing an empty string as the url parameter will mark it as unset, making url then return None.

Panics

This function will also panic if the given URL contains NULL-byte characters, which are invalid.

pub fn manual_url(&self) -> Option<&CStr>

The URL of this plugin’s user’s manual.

Example: https://dl.u-he.com/manuals/plugins/diva/Diva-user-guide.pdf.

This method will return None if this is either missing or a blank (i.e. empty) string.

pub fn with_manual_url(self, manual_url: &str) -> Self

Sets the plugin’s manual’s URL.

See the url method documentation for more information.

Passing an empty string as the url parameter will mark it as unset, making url then return None.

Panics

This function will also panic if the given URL contains NULL-byte characters, which are invalid.

pub fn support_url(&self) -> Option<&CStr>

The URL of this plugin’s support page.

Example: https://u-he.com/support/.

This method will return None if this is either missing or a blank (i.e. empty) string.

pub fn with_support_url(self, support_url: &str) -> Self

Sets the plugin’s support URL.

See the support_url method documentation for more information.

Passing an empty string as the support_url parameter will mark it as unset, making support_url then return None.

Panics

This function will also panic if the given URL contains NULL-byte characters, which are invalid.

pub fn version(&self) -> Option<&CStr>

The version string of this plugin.

While Semver-compatible version strings are preferred, this field can contain any arbitrary string.

Example: 1.4.4.

This method will return None if this is either missing or a blank (i.e. empty) string.

pub fn with_version(self, version: &str) -> Self

Sets the plugin’s version string.

See the version method documentation for more information.

Passing an empty string as the version parameter will mark it as unset, making version then return None.

Panics

This function will also panic if the given version string contains NULL-byte characters, which are invalid.

pub fn description(&self) -> Option<&CStr>

A short description of this plugin.

Example: The spirit of analogue.

This method will return None if this is either missing or a blank (i.e. empty) string.

pub fn with_description(self, description: &str) -> Self

Sets the plugin’s description.

See the description method documentation for more information.

Passing an empty string as the description parameter will mark it as unset, making description then return None.

Panics

This function will also panic if the given description contains NULL-byte characters, which are invalid.

pub fn features(&self) -> FeaturesIter<'_>

An arbitrary list of tags that can be used by hosts to classify this plugin.

For some standard features, see the constants in the features module.

Example: "instrument", "synthesizer", "stereo".

pub fn with_features<'a>( self, features: impl IntoIterator<Item = &'a CStr>, ) -> Self

Sets the plugin’s feature list.

See the features method documentation for more information.

Trait Implementations

impl Clone for PluginDescriptor

fn clone(&self) -> PluginDescriptor

Returns a duplicate of the value.

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

Performs copy-assignment from source.