Struct Invocation 

pub struct Invocation<'a> { /* private fields */ }

What an action was given when it ran.

Two sources, and keeping them apart is the whole design. Parameters were chosen when the binding was authored and are saved with it; the value was produced by the input a moment ago and is saved nowhere. Merging them into one map would let a fader position be persisted, which is the sort of thing that works until someone restarts the daemon and their volume jumps.

Implementations

impl<'a> Invocation<'a>

pub fn press(params: &'a BTreeMap<String, ParamValue>) -> Self

A press, with the binding’s parameters.

pub fn moved(params: &'a BTreeMap<String, ParamValue>, value: u16) -> Self

A position, with the binding’s parameters.

pub fn bare() -> Self

A press with nothing configured. For tests, and for actions that take no parameters.

pub fn from(self, input: &'a str) -> Self

Say which input this came from.

A builder rather than a fourth argument, so every existing call still compiles and reads the same. The host adds it; an addon never does.

pub fn input(&self) -> Option<&str>

Which input fired, as the same opaque string Addon::bound_inputs lists.

None when the interface asked rather than a key: there is no input, and inventing one would name a key that does not exist.

Opaque, and meant to stay that way. It is a key to match against the ordered list, not something to parse — the order is the daemon’s answer, because only the daemon knows where the modules physically are.

pub fn param(&self, id: &str) -> Option<&str>

One parameter, if the binding set it.

Absent and empty are the same answer here. A text box someone cleared stores "", and an addon checking only for absence would then treat a deliberately blank field as a configured one. A parameter holding a list reads as absent here, rather than as its first entry. See ParamValue::one: an addon that declared one value and silently used the first of several would mute one of the three applications somebody named and report nothing.

pub fn param_all(&self, id: &str) -> Vec<&str>

Every value of one parameter, whether it holds one or several.

The accessor a multiple parameter reads. A single value reads as a list of one, so an addon does not have to care how the user happened to fill it in — and a configuration written before lists existed contains exactly that case.

pub fn raw_params(&self) -> &BTreeMap<String, ParamValue>

The map as it was stored, for a host that has to forward it verbatim.

Not for addons: an addon wants Self::param or Self::param_all. This exists because the daemon builds an invocation on one side of a pipe and has to put the same thing back on the wire on the other, and re-deriving it from the accessors would turn a list into whatever the accessors happened to flatten it to.

pub fn params(&self) -> impl Iterator<Item = (&str, String)>

Every parameter, for reporting.

A list renders comma-separated, because this feeds a log line rather than anything that parses it back.

pub fn value(&self) -> Option<u16>

The raw position, 0..=16383, for a continuous action.

pub fn fraction(&self) -> Option<f32>

The position as a fraction of full travel, 0.0..=1.0.

Provided so the common case is one call rather than a division everyone writes slightly differently. Not a taper: audio wants a curve, and only the addon knows whether its target is already logarithmic.

Trait Implementations

impl<'a> Clone for Invocation<'a>

fn clone(&self) -> Invocation<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Invocation<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Copy for Invocation<'a>