Something went wrong. Try again.
A Zig library for talking to USB and Bluetooth HID devices on Linux, FreeBSD, Windows and macOS, without linking the C hidapi
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130// SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! What can go wrong, named once for every backend.//!//! These sets are explicit rather than inferred. An inferred set changes shape//! when a backend is added, which for a library means a caller's `switch` can//! stop compiling because someone else's operating system grew a failure mode;//! it also means the published reference lists whatever set the machine that//! built the documentation happened to produce. Naming them fixes both.//!//! The one deliberate catch-all is `DeviceRefused`. Enumerating every `errno`,//! `NTSTATUS` and `IOReturn` into the public sets would make them differ per//! target and force callers to handle failures that cannot happen where they//! are, so the native code is logged at warning level and the error says what//! happened rather than which number said so.
const std = @import("std");
/// The failures any call that touches a device can produce.pub const DeviceError = error{ /// The process may not talk to this device. On Linux and FreeBSD the /// device node is root-only until a udev or devd rule says otherwise; on /// Windows the system holds keyboards and pointing devices open /// exclusively; on macOS the process has not been granted Input /// Monitoring. The README has the fix for each. AccessDenied,
/// Nothing answers to that `DeviceId`. Either it was never valid on this /// system, or it names a device that was gone before the call. Enumerate /// again. DeviceNotFound,
/// The device was there when the call began and is not now. /// /// Separate from `DeviceNotFound` because the answers differ: this one /// means stop, that one means look again. It is the expected end of a /// `read` loop over a device someone unplugs, which used to be /// indistinguishable from a malformed report. DeviceDisconnected,
/// The operating system or the device rejected the request -- a report ID /// it does not know, a transfer the transport does not carry, a report the /// wrong length for it. The underlying code is logged at warning level /// before this is returned. DeviceRefused,
/// A resource belonging to the operating system ran out: file /// descriptors, handles, kernel memory. Distinct from the caller's own /// allocator failing, which this library never does, because it does not /// allocate. SystemResources,};
/// `Device.open`.////// `ConcurrentError` is here on every target, not only on macOS. Only macOS/// can produce it -- a device there owns a task for its whole life, so an `Io`/// with a bounded `concurrent_limit` can refuse to open one -- but a set that/// changes shape per target is the thing these declarations exist to avoid.////// `BufferTooSmall` means `OpenOptions.input_queue` cannot hold a single input/// report from this device.pub const OpenError = DeviceError || std.Io.Cancelable || std.Io.ConcurrentError || error{ BufferTooSmall, DeviceIdTooLong };
/// `Enumerator.init` and `Enumerator.next`.////// `BufferTooSmall` means the scratch buffer could not hold this system's/// device list; `Enumerator.recommended_scratch` is sized so that it does not/// happen in practice.pub const EnumerateError = DeviceError || std.Io.Cancelable || std.Io.ConcurrentError || error{BufferTooSmall};
/// `Device.read` and `Device.readTimeout`.////// There is no `WouldBlock`: a non-blocking read is `readTimeout` with a zero/// duration, and it reports having found nothing by returning `null`, which is/// also what a real timeout returns. A zero-length input report is a legal/// thing for a device to send, so the two cases cannot share a representation.pub const ReadError = DeviceError || std.Io.Cancelable || error{BufferTooSmall};
/// `Device.write`.pub const WriteError = DeviceError || std.Io.Cancelable || error{ReportTooLarge};
/// `Device.getFeatureReport`, `sendFeatureReport` and `getInputReport`.pub const ReportError = DeviceError || std.Io.Cancelable || error{ ReportTooLarge, BufferTooSmall };
/// `Device.getReportDescriptor` and `getReportDescriptorLen`.pub const DescriptorError = DeviceError || std.Io.Cancelable || error{ BufferTooSmall,
/// This backend cannot produce a HID report descriptor. /// /// Windows always: the HID class driver keeps only its own parsed form of /// the descriptor and does not serve the original bytes to user mode. /// macOS for the occasional device that publishes no descriptor property. Unsupported,};
/// Every error any call in this library can return, for a caller that wants/// one `catch` for the lot.pub const AnyError = OpenError || EnumerateError || ReadError || WriteError || ReportError || DescriptorError;
test "the per-operation sets are all subsets of AnyError" { // If this stops compiling, a set above gained a member that `AnyError` // does not name, and a caller switching exhaustively on `AnyError` would // silently stop seeing it. inline for (.{ OpenError, EnumerateError, ReadError, WriteError, ReportError, DescriptorError }) |Set| { inline for (@typeInfo(Set).error_set.error_names.?) |name| { // Coercing rather than merely naming it is what makes this a // check: an error `AnyError` does not hold fails to coerce. const member: AnyError = @field(anyerror, name); _ = member catch {}; } }}
test "DeviceNotFound and DeviceDisconnected are distinct" { // The whole reason both exist. A caller reading in a loop stops on one and // re-enumerates on the other, so collapsing them would be a real loss. try std.testing.expect(error.DeviceNotFound != error.DeviceDisconnected);}
test { std.testing.refAllDecls(@This());}