SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
3D mouse: find devices on Windows without asking every HID device for its strings (#2614) (#3653)
Tyler Chiriboga6f5d0038abff
diff --git a/AGENTS.md b/AGENTS.mdindex 5551a0e9e7..0720afeeff 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -33,9 +33,11 @@ People trust SolidCraft with their designs; a crash loses their work. **This outand calls through its function pointers), two functions in`apps/solidcraft/src/open_documents.rs` (macOS hands Finder files only to an Objective-Cmethod), the Windows-only `apps/solidcraft/src/native_crash.rs` (the exception filter that- records crashes inside native code such as graphics drivers) and the Windows-only+ records crashes inside native code such as graphics drivers), the Windows-only`apps/solidcraft/src/native_frame.rs` (the window procedure that answers the resize-border hit- test of the window without OS decorations).+ test of the window without OS decorations) and the Windows-only+ `apps/solidcraft/src/space_mouse/windows_hid.rs` (asks Plug and Play which HID interfaces are 3D+ mice, so no other device is sent anything).- **Errors are `Result<T, E>`** through the crate's error type and `?`. An unfinished featurereturns an error ("not supported yet: …"); it never panics.- **Input-derived numbers are hostile** (command parameters, design files, control-channeldiff --git a/apps/solidcraft/Cargo.toml b/apps/solidcraft/Cargo.tomlindex 0fcde99f5c..5078470dd5 100644--- a/apps/solidcraft/Cargo.toml+++ b/apps/solidcraft/Cargo.toml@@ -50,7 +50,11 @@ hidapi = { version = "2.6.7", default-features = false, features = ["windows-natraw-window-handle = "0.6"# Native crash capture (src/native_crash.rs): the exception filter, the faulting module, a minidump.# The window's resize border and DPI size (src/native_frame.rs): the window procedure, hit test, DPI.+# Finding 3D mice through Plug and Play without asking other devices anything (src/space_mouse/windows_hid.rs).windows-sys = { version = "0.61", features = [+ "Win32_Devices_DeviceAndDriverInstallation",+ "Win32_Devices_HumanInterfaceDevice",+ "Win32_Devices_Properties","Win32_Foundation","Win32_Graphics_Gdi","Win32_Security",diff --git a/apps/solidcraft/src/space_mouse.rs b/apps/solidcraft/src/space_mouse.rsindex 245107f2bb..8a9c31818a 100644--- a/apps/solidcraft/src/space_mouse.rs+++ b/apps/solidcraft/src/space_mouse.rs@@ -7,7 +7,11 @@mod hidraw;#[cfg(target_os = "linux")]mod spacenavd;+#[cfg(target_os = "windows")]+mod windows_hid;+#[cfg(any(target_os = "windows", target_os = "macos"))]+use std::ffi::CString;#[cfg(target_os = "linux")]use std::sync::atomic::AtomicU8;use std::sync::atomic::{AtomicBool, Ordering};@@ -15,8 +19,10 @@ use std::sync::{Arc, Mutex};use std::time::{Duration, Instant};use egui::Context;+#[cfg(target_os = "macos")]+use hidapi::DeviceInfo;#[cfg(any(target_os = "windows", target_os = "macos"))]-use hidapi::{DeviceInfo, HidApi};+use hidapi::HidApi;use quick_xml::Reader;use quick_xml::events::Event;use solidcraft_space_mouse::Layout;@@ -256,8 +262,9 @@ fn at_rest(calibration: Option<Calibration>) -> Axes {}/// The Generic Desktop "Multi-Axis Controller" usage names a 3D mouse's motion interface, whoever-/// made it, and excludes ordinary mice and the keyboard interfaces of 3D mice.-#[cfg(any(target_os = "windows", target_os = "macos"))]+/// made it, and excludes ordinary mice and the keyboard interfaces of 3D mice. (Windows asks Plug+/// and Play for the same usage: `windows_hid`.)+#[cfg(target_os = "macos")]fn is_3d_mouse(info: &DeviceInfo) -> bool {info.usage_page() == 0x01 && info.usage() == 0x08}@@ -317,18 +324,48 @@ fn reset(ctx: &Context, shared: &Mutex<Reading>) {ctx.request_repaint();}+/// The HID interfaces that are 3D mice, by path. Windows asks Plug and Play, which sends nothing to+/// the devices: hidapi's enumeration would ask every keyboard and mouse for its strings on each scan+/// (#2614, `windows_hid`).+#[cfg(target_os = "windows")]+fn candidates(_api: &mut HidApi) -> Vec<CString> {+ windows_hid::multi_axis_controllers()+}++/// The HID interfaces that are 3D mice, by path, from hidapi's enumeration (IOKit's registry).+#[cfg(target_os = "macos")]+fn candidates(api: &mut HidApi) -> Vec<CString> {+ if let Err(error) = api.refresh_devices() {+ log::warn!("3D mouse: device scan failed: {error}");+ return Vec::new();+ }+ api.device_list().filter(|info| is_3d_mouse(info)).map(|info| info.path().to_owned()).collect()+}++/// The HID context. On Windows hidapi's own device discovery is off, so making it asks no device+/// anything either (`candidates` finds the 3D mice). Turning discovery off panics only once a+/// context with discovery exists; the reader is the one place the app makes a context, once.+#[cfg(target_os = "windows")]+fn hid_api() -> hidapi::HidResult<HidApi> {+ HidApi::disable_device_discovery();+ HidApi::new()+}++#[cfg(target_os = "macos")]+fn hid_api() -> hidapi::HidResult<HidApi> {+ HidApi::new()+}+#[cfg(any(target_os = "windows", target_os = "macos"))]fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {- let Ok(mut api) = HidApi::new() else {+ let Ok(mut api) = hid_api() else {log::warn!("3D mouse: HID initialization failed");return;};loop {- if let Err(error) = api.refresh_devices() {- log::warn!("3D mouse: device scan failed: {error}");- } else if let Some((device, layout, ids)) = api.device_list().filter(|info| is_3d_mouse(info)).find_map(|info| {- let device = info- .open_device(&api)+ if let Some((device, layout, ids)) = candidates(&mut api).into_iter().find_map(|path| {+ let device = api+ .open_path(&path).inspect_err(|error| {// On macOS: missing Input Monitoring permission, or the 3DxWare helper holding the device.// The driver having the device is the reason it cannot be opened, not a problem.@@ -337,6 +374,8 @@ fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {}}).ok()?;+ // Read when the device was opened, from this device alone.+ let info = device.get_device_info().ok()?;let layout = device_layout(&device, info.vendor_id())?;Some((device, layout, (info.vendor_id(), info.product_id())))}) {diff --git a/apps/solidcraft/src/space_mouse/windows_hid.rs b/apps/solidcraft/src/space_mouse/windows_hid.rsnew file mode 100644index 0000000000..473798ed60--- /dev/null+++ b/apps/solidcraft/src/space_mouse/windows_hid.rs@@ -0,0 +1,172 @@+//! Windows: finding 3D mice without asking any other device anything (#2614).+//!+//! hidapi's enumeration opens every HID interface and reads its serial number, manufacturer and+//! product strings: on USB, three control requests to every keyboard, mouse and touchscreen. The+//! reader repeated it every two seconds while no 3D mouse was plugged in, and on some machines the+//! keyboard then kept dropping off the bus and the cursor jumped. Plug and Play already names each+//! interface's top-level usage in its hardware IDs (`HID_DEVICE_UP:0001_U:0008`: Generic Desktop,+//! Multi-Axis Controller), so the reader asks it, which sends nothing to any device, and opens only+//! the interfaces that are 3D mice.+//!+//! The configuration manager has no safe API, hence the `unsafe_code` allowance on this module+//! (the app crate denies it; see `native_crash.rs`).+#![allow(unsafe_code)]++use std::ffi::CString;+use std::ptr::{null, null_mut};++use windows_sys::Win32::Devices::DeviceAndDriverInstallation::{+ CM_GET_DEVICE_INTERFACE_LIST_PRESENT, CM_Get_DevNode_PropertyW, CM_Get_Device_Interface_List_SizeW, CM_Get_Device_Interface_ListW,+ CM_Get_Device_Interface_PropertyW, CM_LOCATE_DEVNODE_NORMAL, CM_Locate_DevNodeW, CONFIGRET, CR_BUFFER_SMALL, CR_SUCCESS,+};+use windows_sys::Win32::Devices::HumanInterfaceDevice::GUID_DEVINTERFACE_HID;+use windows_sys::Win32::Devices::Properties::{+ DEVPKEY_Device_HardwareIds, DEVPKEY_Device_InstanceId, DEVPROP_TYPE_STRING, DEVPROP_TYPE_STRING_LIST, DEVPROPTYPE,+};+use windows_sys::Win32::Foundation::DEVPROPKEY;++/// The hardware ID Windows gives a top-level collection with the Generic Desktop page's+/// Multi-Axis Controller usage.+const MULTI_AXIS_CONTROLLER: &str = "HID_DEVICE_UP:0001_U:0008";+/// Largest property read, in bytes: hardware IDs are a few hundred.+const MAX_PROPERTY_BYTES: u32 = 64 * 1024;+/// Tries at reading the interface list, which can grow between asking its size and reading it.+const LIST_TRIES: usize = 4;++/// The paths of the present HID interfaces whose top-level collection is a multi-axis controller.+pub fn multi_axis_controllers() -> Vec<CString> {+ interfaces()+ .into_iter()+ .filter(|path| {+ let Some(instance) = interface_strings(path, &DEVPKEY_Device_InstanceId).and_then(|ids| ids.into_iter().next()) else {+ return false;+ };+ devnode_strings(&instance, &DEVPKEY_Device_HardwareIds).is_some_and(|ids| is_multi_axis(&ids))+ })+ .filter_map(|path| CString::new(path).ok())+ .collect()+}++/// Whether a device with these hardware IDs is a multi-axis controller.+fn is_multi_axis(hardware_ids: &[String]) -> bool {+ hardware_ids.iter().any(|id| id.eq_ignore_ascii_case(MULTI_AXIS_CONTROLLER))+}++/// The strings of a nul-separated list (`REG_MULTI_SZ`, or one string), without empty ones.+fn split_multi_sz(buffer: &[u16]) -> Vec<String> {+ buffer.split(|c| *c == 0).filter(|s| !s.is_empty()).map(String::from_utf16_lossy).collect()+}++/// `s` as a nul-terminated wide string.+fn wide(s: &str) -> Vec<u16> {+ s.encode_utf16().chain(std::iter::once(0)).collect()+}++/// The paths of the present HID interfaces.+fn interfaces() -> Vec<String> {+ for _ in 0..LIST_TRIES {+ let mut len = 0u32;+ // SAFETY: `len` is a valid place for the size; the class GUID is a static; no device filter.+ let sized = unsafe { CM_Get_Device_Interface_List_SizeW(&mut len, &GUID_DEVINTERFACE_HID, null(), CM_GET_DEVICE_INTERFACE_LIST_PRESENT) };+ if sized != CR_SUCCESS || len == 0 {+ return Vec::new();+ }+ let mut buffer = vec![0u16; len as usize];+ // SAFETY: `buffer` holds `len` wide characters, the length the call is given.+ let listed =+ unsafe { CM_Get_Device_Interface_ListW(&GUID_DEVINTERFACE_HID, null(), buffer.as_mut_ptr(), len, CM_GET_DEVICE_INTERFACE_LIST_PRESENT) };+ match listed {+ CR_SUCCESS => return split_multi_sz(&buffer),+ CR_BUFFER_SMALL => continue,+ _ => return Vec::new(),+ }+ }+ Vec::new()+}++/// A string or string-list property, read by `get` (property type, buffer, its size in bytes) in+/// two calls: the size, then the value.+fn property_strings(get: impl Fn(*mut DEVPROPTYPE, *mut u8, *mut u32) -> CONFIGRET) -> Option<Vec<String>> {+ let mut kind: DEVPROPTYPE = 0;+ let mut size = 0u32;+ if get(&mut kind, null_mut(), &mut size) != CR_BUFFER_SMALL || size == 0 || size > MAX_PROPERTY_BYTES {+ return None;+ }+ let mut buffer = vec![0u16; (size as usize).div_ceil(2)];+ let mut size = (buffer.len() * 2) as u32;+ if get(&mut kind, buffer.as_mut_ptr().cast(), &mut size) != CR_SUCCESS || (kind != DEVPROP_TYPE_STRING && kind != DEVPROP_TYPE_STRING_LIST) {+ return None;+ }+ Some(split_multi_sz(&buffer))+}++/// A string property of the device interface at `path`.+fn interface_strings(path: &str, key: &DEVPROPKEY) -> Option<Vec<String>> {+ let path = wide(path);+ property_strings(|kind, buffer, size| {+ // SAFETY: `path` is nul-terminated and outlives the call; `buffer` is null (asking the size)+ // or holds `*size` bytes, as `property_strings` sets up.+ unsafe { CM_Get_Device_Interface_PropertyW(path.as_ptr(), key, kind, buffer, size, 0) }+ })+}++/// A string property of the device with instance ID `instance`.+fn devnode_strings(instance: &str, key: &DEVPROPKEY) -> Option<Vec<String>> {+ let instance = wide(instance);+ let mut devnode = 0u32;+ // SAFETY: `instance` is nul-terminated and outlives the call; `devnode` is a valid place for the result.+ if unsafe { CM_Locate_DevNodeW(&mut devnode, instance.as_ptr(), CM_LOCATE_DEVNODE_NORMAL) } != CR_SUCCESS {+ return None;+ }+ property_strings(|kind, buffer, size| {+ // SAFETY: `buffer` is null (asking the size) or holds `*size` bytes, as `property_strings` sets up.+ unsafe { CM_Get_DevNode_PropertyW(devnode, key, kind, buffer, size, 0) }+ })+}++#[cfg(test)]+mod tests {+ use super::*;++ /// The hardware IDs Windows gives a wired 3Dconnexion device's motion interface, and a+ /// keyboard's: only the first is a multi-axis controller.+ #[test]+ fn only_the_multi_axis_usage_is_a_3d_mouse() {+ let ids = |list: &[&str]| list.iter().map(|s| s.to_string()).collect::<Vec<_>>();+ let space_mouse = ids(&["HID\\VID_256F&PID_C635&REV_0437&MI_00", "HID\\VID_256F&UP:0001_U:0008", "HID_DEVICE_UP:0001_U:0008", "HID_DEVICE"]);+ let keyboard = ids(&[+ "HID\\VID_046D&PID_C31C&REV_6400&MI_00",+ "HID\\VID_046D&UP:0001_U:0006",+ "HID_DEVICE_SYSTEM_KEYBOARD",+ "HID_DEVICE_UP:0001_U:0006",+ "HID_DEVICE",+ ]);+ let vendor = ids(&["HID\\VID_256F&UP:FF00_U:0001", "HID_DEVICE_UP:FF00_U:0001", "HID_DEVICE_UPR:FF00-FFFF", "HID_DEVICE"]);+ assert!(is_multi_axis(&space_mouse));+ assert!(is_multi_axis(&ids(&["hid_device_up:0001_u:0008"])), "IDs compare without regard to case");+ assert!(!is_multi_axis(&keyboard) && !is_multi_axis(&vendor) && !is_multi_axis(&[]));+ }++ #[test]+ fn nul_separated_lists_split_into_their_strings() {+ let buffer: Vec<u16> = "a\\b\0HID_DEVICE\0\0".encode_utf16().collect();+ assert_eq!(split_multi_sz(&buffer), ["a\\b", "HID_DEVICE"]);+ assert_eq!(split_multi_sz(&wide("one")), ["one"]);+ assert!(split_multi_sz(&[0, 0]).is_empty() && split_multi_sz(&[]).is_empty());+ }++ /// The scan asks Plug and Play only: on any machine it returns, and every path it returns is a+ /// present HID interface whose hardware IDs name the multi-axis usage.+ #[test]+ fn the_scan_returns_only_multi_axis_interfaces() {+ let found = multi_axis_controllers();+ let all = interfaces();+ for path in &found {+ let path = path.to_str().unwrap_or_default();+ assert!(all.iter().any(|p| p == path), "{path}");+ let instance = interface_strings(path, &DEVPKEY_Device_InstanceId).and_then(|ids| ids.into_iter().next()).unwrap_or_default();+ assert!(devnode_strings(&instance, &DEVPKEY_Device_HardwareIds).is_some_and(|ids| is_multi_axis(&ids)), "{path}");+ }+ eprintln!("{} HID interfaces present, {} multi-axis controllers", all.len(), found.len());+ }+}