1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
//! CLAP provider discovery data. No common CLAP preset file encoding is implied.
use std::path::PathBuf;
/// Maximum UTF-8 bytes accepted for one provider text field.
pub const PRESET_DISCOVERY_TEXT_BYTES: usize = 16384;
bitflags::bitflags! {
/// What a CLAP preset provider says of a location's, soundpack's or preset's content. Bits
/// that later CLAP versions define are kept, though they have no name here.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub struct PresetFlags: u32 {
/// Content that comes with the plugin.
const FACTORY_CONTENT = 1 << 0;
/// Content the user made.
const USER_CONTENT = 1 << 1;
/// Content for demonstration.
const DEMO_CONTENT = 1 << 2;
/// Content the user marked as a favorite.
const FAVORITE = 1 << 3;
}
}
/// Native CLAP provider location used both for discovery and preset loading.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum PresetLocation {
/// Presets stored internally by the plugin rather than in a filesystem location.
Plugin,
/// A preset file or directory exposed by a provider.
File {
/// Native preset file or directory path.
path: PathBuf,
},
}
/// One provider and location to inspect without loading an audio instance.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct PresetDiscoveryTarget {
/// Native provider ID within its CLAP module.
pub provider_id: String,
/// Internal plugin storage or the provider’s filesystem location.
pub location: PresetLocation,
}
impl PresetDiscoveryTarget {
/// `location` searched with the provider `provider_id`.
#[must_use]
pub fn new(provider_id: impl Into<String>, location: PresetLocation) -> PresetDiscoveryTarget {
PresetDiscoveryTarget {
provider_id: provider_id.into(),
location,
}
}
/// Checks the target before any provider code runs: a provider ID and, for a file location,
/// an absolute Unicode path, each non-empty, without NUL and within
/// [`PRESET_DISCOVERY_TEXT_BYTES`].
pub fn validate(&self) -> Result<(), crate::InputError> {
let text = |value: &str| {
!value.is_empty() && value.len() <= PRESET_DISCOVERY_TEXT_BYTES && !value.contains('\0')
};
let location = match &self.location {
PresetLocation::Plugin => true,
PresetLocation::File { path } => path.is_absolute() && path.to_str().is_some_and(text),
};
if text(&self.provider_id) && location {
Ok(())
} else {
Err(crate::InputError::PresetDiscoveryTarget)
}
}
}
/// File type advertised by a CLAP preset provider.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct PresetFileType {
/// Native display name.
pub name: String,
/// Optional native descriptive text.
pub description: Option<String>,
/// File extension advertised by the provider, without a leading dot.
pub extension: Option<String>,
}
impl PresetFileType {
/// Each field as given. Internal to the plughost crates; exempt from semver.
#[doc(hidden)]
#[must_use]
pub fn new(
name: String,
description: Option<String>,
extension: Option<String>,
) -> PresetFileType {
PresetFileType {
name,
description,
extension,
}
}
}
/// Named discovery location advertised by a CLAP provider.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct PresetLocationInfo {
/// Native display name.
pub name: String,
/// What the provider says of the location's content.
pub flags: PresetFlags,
/// Internal plugin storage or the provider’s filesystem location.
pub location: PresetLocation,
}
impl PresetLocationInfo {
/// Each field as given. Internal to the plughost crates; exempt from semver.
#[doc(hidden)]
#[must_use]
pub fn new(name: String, flags: PresetFlags, location: PresetLocation) -> PresetLocationInfo {
PresetLocationInfo {
name,
flags,
location,
}
}
}
/// Native metadata for a provider’s soundpack.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct PresetSoundpack {
/// Native identifier, scoped to the owning provider or ABI.
pub id: String,
/// Native display name.
pub name: String,
/// What the provider says of the soundpack's content.
pub flags: PresetFlags,
/// Optional native descriptive text.
pub description: Option<String>,
/// Provider-supplied homepage URL; not fetched by discovery.
pub homepage_url: Option<String>,
/// Native vendor name, when supplied.
pub vendor: Option<String>,
/// Provider-supplied artwork path, when supplied.
pub image_path: Option<String>,
/// Release time in seconds since the Unix epoch, when supplied.
pub release_timestamp: Option<u64>,
}
impl PresetSoundpack {
/// A soundpack with no optional metadata yet, which the fields then take. Internal to the
/// plughost crates; exempt from semver.
#[doc(hidden)]
#[must_use]
pub fn new(id: String, name: String, flags: PresetFlags) -> PresetSoundpack {
PresetSoundpack {
id,
name,
flags,
description: None,
homepage_url: None,
vendor: None,
image_path: None,
release_timestamp: None,
}
}
}
/// A CLAP module’s preset provider and its advertised discovery metadata.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct PresetProviderInfo {
/// Native identifier, scoped to the owning provider or ABI.
pub id: String,
/// Native display name.
pub name: String,
/// Native vendor name, when supplied.
pub vendor: Option<String>,
/// Native file types accepted by this provider.
pub file_types: Vec<PresetFileType>,
/// Locations this provider offers for discovery.
pub locations: Vec<PresetLocationInfo>,
/// Soundpacks advertised by this provider.
pub soundpacks: Vec<PresetSoundpack>,
}
impl PresetProviderInfo {
/// Each field as given. Internal to the plughost crates; exempt from semver.
#[doc(hidden)]
#[must_use]
pub fn new(
id: String,
name: String,
vendor: Option<String>,
file_types: Vec<PresetFileType>,
locations: Vec<PresetLocationInfo>,
soundpacks: Vec<PresetSoundpack>,
) -> PresetProviderInfo {
PresetProviderInfo {
id,
name,
vendor,
file_types,
locations,
soundpacks,
}
}
}
/// Native plugin ABI and identity to which a discovered preset applies.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct PresetPluginId {
/// Provider-supplied ABI name, such as `clap`.
pub abi: String,
/// Native identifier, scoped to the owning provider or ABI.
pub id: String,
}
impl PresetPluginId {
/// Each field as given. Internal to the plughost crates; exempt from semver.
#[doc(hidden)]
#[must_use]
pub fn new(abi: String, id: String) -> PresetPluginId {
PresetPluginId { abi, id }
}
}
/// One native preset discovered by a CLAP provider.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct DiscoveredPreset {
/// The plugin location, or the file that holds this preset; load it with this location.
pub location: PresetLocation,
/// Preset display name, when supplied.
pub name: Option<String>,
/// Opaque provider key identifying a preset inside its location.
pub load_key: Option<String>,
/// Plugin identities to which the provider says this preset applies.
pub plugin_ids: Vec<PresetPluginId>,
/// Owning soundpack ID, when supplied.
pub soundpack_id: Option<String>,
/// What the provider says of the preset, or `None` if it did not say.
pub flags: Option<PresetFlags>,
/// Creator names in the order reported by the provider.
pub creators: Vec<String>,
/// Optional native descriptive text.
pub description: Option<String>,
/// Creation time in seconds since the Unix epoch, when supplied.
pub creation_time: Option<u64>,
/// Modification time in seconds since the Unix epoch, when supplied.
pub modification_time: Option<u64>,
/// Native feature/category strings in provider order.
pub features: Vec<String>,
/// Additional native key/value metadata, preserved without interpretation.
pub extra_info: Vec<(String, String)>,
}
impl DiscoveredPreset {
/// A preset at `location` with no metadata yet; the fields take what the provider reports.
#[must_use]
pub fn new(location: PresetLocation) -> DiscoveredPreset {
DiscoveredPreset {
location,
name: None,
load_key: None,
plugin_ids: Vec::new(),
soundpack_id: None,
flags: None,
creators: Vec::new(),
description: None,
creation_time: None,
modification_time: None,
features: Vec::new(),
extra_info: Vec::new(),
}
}
}
/// Presets found at one provider location. A file in a crawled directory that the provider
/// refused is listed with its failure instead of failing the other files.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct PresetDiscovery {
/// Successfully discovered presets, in observed order.
pub presets: Vec<DiscoveredPreset>,
/// Individual files refused by the provider during directory discovery.
pub failed_files: Vec<PresetFileFailure>,
}
impl PresetDiscovery {
/// Each field as given. Internal to the plughost crates; exempt from semver.
#[doc(hidden)]
#[must_use]
pub fn new(
presets: Vec<DiscoveredPreset>,
failed_files: Vec<PresetFileFailure>,
) -> PresetDiscovery {
PresetDiscovery {
presets,
failed_files,
}
}
}
/// One preset file’s discovery failure, without failing the surrounding directory.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct PresetFileFailure {
/// Preset file that could not be inspected.
pub path: PathBuf,
/// Portable failure category and native diagnostic.
pub failure: crate::Failure,
}
impl PresetFileFailure {
/// Each field as given. Internal to the plughost crates; exempt from semver.
#[doc(hidden)]
#[must_use]
pub fn new(path: PathBuf, failure: crate::Failure) -> PresetFileFailure {
PresetFileFailure { path, failure }
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_target_takes_a_provider_id_and_an_absolute_unicode_path_within_the_text_limit() {
let file = |path: PathBuf| PresetLocation::File { path };
let absolute = std::env::temp_dir().join("preset.phcp");
for (provider, location) in [
("provider", PresetLocation::Plugin),
("provider", file(absolute.clone())),
] {
assert_eq!(
PresetDiscoveryTarget::new(provider, location).validate(),
Ok(())
);
}
let long = "x".repeat(PRESET_DISCOVERY_TEXT_BYTES + 1);
for (provider, location) in [
("", PresetLocation::Plugin),
("pro\0vider", PresetLocation::Plugin),
(long.as_str(), PresetLocation::Plugin),
("provider", file("relative.phcp".into())),
("provider", file(std::env::temp_dir().join("pre\0set.phcp"))),
] {
assert_eq!(
PresetDiscoveryTarget::new(provider, location).validate(),
Err(crate::InputError::PresetDiscoveryTarget)
);
}
}
}