1#![warn(clippy::undocumented_unsafe_blocks)]
8
9use std::ffi::c_void;
10use std::mem::size_of;
11
12#[doc(hidden)]
13pub mod export;
14mod interfaces;
15
16pub use interfaces::*;
17
18pub const VESPER_PLUGIN_ENTRY_SYMBOL: &[u8] = b"vesper_plugin_entry\0";
20pub const VESPER_PLUGIN_ENTRY_SYMBOL_NAME: &str = "vesper_plugin_entry";
22
23pub const VESPER_PLUGIN_ABI_MAJOR: u16 = 1;
25pub const VESPER_PLUGIN_ABI_MINOR: u16 = 0;
27
28pub const VESPER_MAX_PLUGIN_ID_BYTES: usize = 255;
30pub const VESPER_MAX_PLUGIN_NAME_BYTES: usize = 255;
32pub const VESPER_MAX_CAPABILITY_INSTANCE_ID_BYTES: usize = 255;
34pub const VESPER_MAX_INTERFACES_PER_PLUGIN: u32 = 64;
36pub const VESPER_MAX_SESSIONS_PER_INTERFACE: usize = 1_024;
38pub const VESPER_MAX_LEASES_PER_SESSION: usize = 64;
40pub const VESPER_MAX_OWNED_BYTES: u64 = 16 * 1024 * 1024;
42pub const VESPER_MAX_PACKET_BYTES: u64 = 16 * 1024 * 1024;
44pub const VESPER_MAX_PCM_BYTES: u64 = 16 * 1024 * 1024;
46
47pub type VesperStatus = u32;
52
53pub mod status {
55 use super::VesperStatus;
56
57 pub const OK: VesperStatus = 0;
58 pub const FAILURE: VesperStatus = 1;
59 pub const INVALID_ARGUMENT: VesperStatus = 2;
60 pub const INCOMPATIBLE: VesperStatus = 3;
61 pub const STALE_HANDLE: VesperStatus = 4;
62 pub const POISONED: VesperStatus = 5;
63 pub const UNSUPPORTED: VesperStatus = 6;
64 pub const CANCELLED: VesperStatus = 7;
65 pub const TIMEOUT: VesperStatus = 8;
66 pub const ABI_VIOLATION: VesperStatus = 9;
67 pub const NOT_FOUND: VesperStatus = 10;
68 pub const AMBIGUOUS: VesperStatus = 11;
69 pub const EXHAUSTED: VesperStatus = 12;
70 pub const PANIC: VesperStatus = 13;
71}
72
73#[repr(transparent)]
78#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
79pub struct VesperInterfaceId(pub [u8; 16]);
80
81pub const POST_DOWNLOAD_PROCESSOR_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
82 0xe9, 0x47, 0x9d, 0xbc, 0x42, 0xd2, 0x57, 0x5e, 0xb3, 0x9e, 0xa2, 0x4b, 0xc5, 0x12, 0xfb, 0xc7,
83]);
84pub const PIPELINE_EVENT_HOOK_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
85 0xc7, 0xa6, 0x94, 0x75, 0x79, 0xb2, 0x5b, 0x5e, 0xa4, 0x77, 0x08, 0x84, 0x4a, 0x5d, 0xa5, 0xd1,
86]);
87pub const BENCHMARK_SINK_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
88 0x2d, 0x8e, 0x5b, 0xe8, 0xb1, 0xde, 0x5e, 0x83, 0x8f, 0xe0, 0x61, 0x18, 0xaa, 0xbc, 0x51, 0x18,
89]);
90pub const NATIVE_DECODER_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
91 0xd6, 0x8b, 0xe0, 0xed, 0x19, 0x58, 0x59, 0x22, 0x8b, 0x7a, 0xbc, 0x67, 0x78, 0xa2, 0x6b, 0x43,
92]);
93pub const FRAME_PROCESSOR_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
94 0xfc, 0x05, 0x05, 0x97, 0xb7, 0xb7, 0x5c, 0x81, 0x83, 0xb9, 0xb4, 0x25, 0x55, 0xf8, 0xb8, 0x25,
95]);
96pub const AUDIO_PROCESSOR_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
97 0xf3, 0xfc, 0x5d, 0x7c, 0x58, 0x1f, 0x5e, 0x0a, 0x85, 0xbf, 0xdf, 0x00, 0xd7, 0xad, 0xb1, 0x3e,
98]);
99pub const SOURCE_NORMALIZER_PACKET_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
100 0xa2, 0xd6, 0x53, 0xfa, 0xd6, 0xce, 0x5f, 0x14, 0x93, 0xb8, 0xa8, 0x18, 0xa7, 0xa7, 0x7f, 0xdf,
101]);
102pub const SOURCE_NORMALIZER_RESOURCE_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
103 0xb7, 0x6d, 0x1f, 0x06, 0x62, 0xd7, 0x5d, 0x71, 0xaa, 0x06, 0x27, 0x80, 0xe4, 0xb4, 0xfd, 0x0d,
104]);
105
106#[repr(C)]
108#[derive(Debug, Clone, Copy, PartialEq, Eq)]
109pub struct VesperByteSlice {
110 pub data: *const u8,
111 pub len: u64,
112}
113
114impl VesperByteSlice {
115 pub const fn empty() -> Self {
116 Self {
117 data: std::ptr::null(),
118 len: 0,
119 }
120 }
121}
122
123impl Default for VesperByteSlice {
124 fn default() -> Self {
125 Self::empty()
126 }
127}
128
129#[repr(C)]
131#[derive(Debug, Clone, Copy, PartialEq, Eq)]
132pub struct VesperOwnedBytes {
133 pub data: *mut u8,
134 pub len: u64,
135}
136
137impl VesperOwnedBytes {
138 pub const fn empty() -> Self {
139 Self {
140 data: std::ptr::null_mut(),
141 len: 0,
142 }
143 }
144
145 #[doc(hidden)]
146 pub fn from_vec(bytes: Vec<u8>) -> Self {
147 if bytes.is_empty() {
148 return Self::empty();
149 }
150 let mut bytes = bytes.into_boxed_slice();
151 let result = Self {
152 data: bytes.as_mut_ptr(),
153 len: bytes.len() as u64,
154 };
155 std::mem::forget(bytes);
156 result
157 }
158
159 #[doc(hidden)]
166 pub unsafe fn into_vec(self) -> Vec<u8> {
167 if self.data.is_null() || self.len == 0 {
168 return Vec::new();
169 }
170 let Ok(len) = usize::try_from(self.len) else {
171 return Vec::new();
172 };
173 unsafe { Box::from_raw(std::ptr::slice_from_raw_parts_mut(self.data, len)).into_vec() }
176 }
177}
178
179impl Default for VesperOwnedBytes {
180 fn default() -> Self {
181 Self::empty()
182 }
183}
184
185#[repr(C)]
187#[derive(Debug, Clone, Copy)]
188pub struct VesperInterfaceHeader {
189 pub struct_size: u32,
190 pub interface_id: VesperInterfaceId,
191 pub major: u16,
192 pub minor: u16,
193 pub context: *mut c_void,
194}
195
196impl VesperInterfaceHeader {
197 pub const fn new(
198 struct_size: u32,
199 interface_id: VesperInterfaceId,
200 major: u16,
201 minor: u16,
202 context: *mut c_void,
203 ) -> Self {
204 Self {
205 struct_size,
206 interface_id,
207 major,
208 minor,
209 context,
210 }
211 }
212}
213
214#[repr(C)]
216#[derive(Debug, Clone, Copy)]
217pub struct VesperInterfaceDescriptor {
218 pub struct_size: u32,
219 pub interface_id: VesperInterfaceId,
220 pub major: u16,
221 pub minor: u16,
222 pub instance_id: VesperByteSlice,
224}
225
226impl Default for VesperInterfaceDescriptor {
227 fn default() -> Self {
228 Self {
229 struct_size: abi_size::<Self>(),
230 interface_id: VesperInterfaceId([0; 16]),
231 major: 0,
232 minor: 0,
233 instance_id: VesperByteSlice::empty(),
234 }
235 }
236}
237
238#[repr(C)]
240#[derive(Debug, Clone, Copy)]
241pub struct VesperPluginRoot {
242 pub struct_size: u32,
243 pub abi_major: u16,
244 pub abi_minor: u16,
245 pub owner: *mut c_void,
247 pub plugin_id: VesperByteSlice,
249 pub plugin_name: VesperByteSlice,
251 pub interface_count: u32,
252 pub reserved: u32,
253 pub interface_at: Option<
254 unsafe extern "C" fn(
255 owner: *mut c_void,
256 index: u32,
257 out_descriptor: *mut VesperInterfaceDescriptor,
258 ) -> VesperStatus,
259 >,
260 pub query_interface: Option<
261 unsafe extern "C" fn(
262 owner: *mut c_void,
263 interface_id: *const VesperInterfaceId,
264 instance_id: VesperByteSlice,
265 requested_major: u16,
266 minimum_minor: u16,
267 out_interface: *mut *const VesperInterfaceHeader,
268 ) -> VesperStatus,
269 >,
270 pub free_bytes: Option<unsafe extern "C" fn(owner: *mut c_void, bytes: VesperOwnedBytes)>,
271 pub destroy_owner: Option<unsafe extern "C" fn(owner: *mut c_void)>,
272}
273
274pub type VesperPluginEntryPoint = unsafe extern "C" fn() -> *const VesperPluginRoot;
276
277pub const fn abi_size<T>() -> u32 {
279 size_of::<T>() as u32
280}
281
282#[cfg(test)]
283mod tests {
284 use std::mem::{align_of, offset_of, size_of};
285
286 use super::*;
287
288 #[test]
289 fn interface_ids_use_canonical_uuid_bytes() {
290 assert_eq!(
291 POST_DOWNLOAD_PROCESSOR_INTERFACE_ID.0,
292 [
293 0xe9, 0x47, 0x9d, 0xbc, 0x42, 0xd2, 0x57, 0x5e, 0xb3, 0x9e, 0xa2, 0x4b, 0xc5, 0x12,
294 0xfb, 0xc7,
295 ]
296 );
297 assert_eq!(SOURCE_NORMALIZER_RESOURCE_INTERFACE_ID.0[0], 0xb7);
298 assert_eq!(SOURCE_NORMALIZER_RESOURCE_INTERFACE_ID.0[15], 0x0d);
299 assert_eq!(
300 AUDIO_PROCESSOR_INTERFACE_ID.0,
301 [
302 0xf3, 0xfc, 0x5d, 0x7c, 0x58, 0x1f, 0x5e, 0x0a, 0x85, 0xbf, 0xdf, 0x00, 0xd7, 0xad,
303 0xb1, 0x3e,
304 ]
305 );
306 }
307
308 #[test]
309 fn interface_header_is_a_stable_table_prefix() {
310 assert_eq!(offset_of!(VesperInterfaceHeader, struct_size), 0);
311 assert_eq!(offset_of!(VesperInterfaceHeader, interface_id), 4);
312 assert_eq!(offset_of!(VesperInterfaceHeader, major), 20);
313 assert_eq!(offset_of!(VesperInterfaceHeader, minor), 22);
314 assert!(offset_of!(VesperInterfaceHeader, context) >= 24);
315 assert_eq!(
316 align_of::<VesperInterfaceHeader>(),
317 align_of::<*mut c_void>()
318 );
319 }
320
321 #[test]
322 fn host_initialized_descriptor_advertises_its_capacity() {
323 let descriptor = VesperInterfaceDescriptor::default();
324 assert_eq!(
325 descriptor.struct_size as usize,
326 size_of::<VesperInterfaceDescriptor>()
327 );
328 assert_eq!(descriptor.interface_id, VesperInterfaceId([0; 16]));
329 assert_eq!(descriptor.instance_id, VesperByteSlice::empty());
330 }
331
332 #[test]
333 fn raw_status_keeps_unknown_values() {
334 let unknown: VesperStatus = u32::MAX;
335 assert_ne!(unknown, status::OK);
336 assert_ne!(unknown, status::FAILURE);
337 }
338
339 #[test]
340 fn root_places_size_and_version_before_pointer_fields() {
341 assert_eq!(offset_of!(VesperPluginRoot, struct_size), 0);
342 assert_eq!(offset_of!(VesperPluginRoot, abi_major), 4);
343 assert_eq!(offset_of!(VesperPluginRoot, abi_minor), 6);
344 assert_eq!(offset_of!(VesperPluginRoot, owner), 8);
345 assert!(size_of::<VesperPluginRoot>() >= size_of::<VesperInterfaceHeader>());
346 }
347}