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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179// SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! Walks the HID devices attached to the system.//!//! ```//! var scratch: [hidapi.Enumerator.recommended_scratch]u8 = undefined;//! var devices: hidapi.Enumerator = undefined;//! try devices.init(io, &scratch, .{});//! defer devices.deinit(io);//!//! while (try devices.next(io)) |info| std.debug.print("{f}\n", .{info});//! ```//!//! Enumerating does not open anything. That is a change from how this library//! used to work, and it is what makes it portable: Windows refuses a//! read-write open of a keyboard or a mouse outright, since the system holds//! those exclusively, and macOS has no file descriptor to hand back at all. It//! also means that on Linux an unprivileged process with no udev rule now sees//! every device rather than none, because `/sys/class/hidraw` is readable//! where `/dev/hidraw*` is not.//!//! The scratch buffer is the caller's, so this library allocates nothing.//! `recommended_scratch` is a size that works; `min_scratch` is the floor//! below which `init` returns `error.BufferTooSmall`. Both are per-backend,//! because what the snapshot costs differs: Linux and FreeBSD read one device//! at a time, while Windows takes the whole interface list in one call and//! macOS copies a set of device references out of IOKit.
const Enumerator = @This();
const std = @import("std");
const backend = @import("backend.zig");const errors = @import("errors.zig");const DeviceInfo = @import("DeviceInfo.zig");
/// What to look for, and how much to find out about it.pub const Options = struct { /// Report only devices with this vendor ID. vendor_id: ?u16 = null, /// Report only devices with this product ID. product_id: ?u16 = null,
/// Fill in `usage_page` and `usage`. /// /// Free on Windows and macOS, which are told. On Linux and FreeBSD it /// means reading and walking a report descriptor for every device, which /// is most of what enumeration costs, so a caller that only wants to match /// on vendor and product can turn it off. usages: bool = true,
/// Fill in `manufacturer`, `product`, `serial_number` and /// `physical_location`. /// /// Four extra sysfs reads per device on Linux. On Windows it is the /// difference between reading the device list and opening a handle to /// every device in it, so turning it off is worth real time on a machine /// with a lot of HID devices. strings: bool = true,};
/// A scratch size that works on this target. Sized so that/// `error.BufferTooSmall` does not happen in practice.pub const recommended_scratch = backend.impl.Enumerator.recommended_scratch;
/// The smallest scratch this target's backend accepts.pub const min_scratch = backend.impl.Enumerator.min_scratch;
impl: backend.impl.Enumerator,/// Where `next` puts the device it found. Held here rather than returned by/// value because a `DeviceInfo` is over a kilobyte, most of which a caller/// filtering on vendor and product never looks at.current: DeviceInfo,
/// Begin enumerating.////// `scratch` has to be at least `min_scratch` bytes and belongs to the/// enumerator until `deinit`. Call `deinit` even when `init` fails to find/// anything: an empty system is a successful enumeration of nothing, not an/// error.pub fn init( self: *Enumerator, io: std.Io, scratch: []u8, options: Options,) errors.EnumerateError!void { self.current = .empty; try self.impl.init(io, scratch, options);}
/// Release whatever the enumeration held. The scratch buffer is the caller's/// again afterwards.pub fn deinit(self: *Enumerator, io: std.Io) void { self.impl.deinit(io);}
/// The next device, or `null` when there are no more.////// The result aliases storage inside the enumerator and is valid only until/// the next call to `next` or to `deinit`. Copy the `DeviceInfo` to keep it,/// or copy just its `id`, which is all `Device.open` needs and which is a/// value with no lifetime of its own.pub fn next(self: *Enumerator, io: std.Io) errors.EnumerateError!?*const DeviceInfo { return if (try self.impl.next(io, &self.current)) &self.current else null;}
/// Find the first device matching `options` and copy its `DeviceInfo` out.////// The common case -- a program that knows which device it wants -- written/// once so that every caller does not repeat the loop and the `deinit`.pub fn find( io: std.Io, scratch: []u8, options: Options, out: *DeviceInfo,) errors.EnumerateError!bool { var self: Enumerator = undefined; try self.init(io, scratch, options); defer self.deinit(io);
if (try self.next(io)) |info| { out.* = info.*; return true; } return false;}
test "enumerate" { const io = std.testing.io;
var scratch: [recommended_scratch]u8 = undefined; var devices: Enumerator = undefined; try devices.init(io, &scratch, .{}); defer devices.deinit(io);
const log = std.log.scoped(.enumerate); var seen: usize = 0; while (try devices.next(io)) |info| { seen += 1; log.info("{f} at {f}", .{ info, &info.id });
// Whatever is attached, these have to hold for all of it. try std.testing.expect(info.id.slice().len > 0); try std.testing.expect(info.manufacturer.slice() == null or info.manufacturer.slice().?.len > 0); }
// Unlike the old iterator, this one does not need permission to open // anything, so on a Linux machine with any HID device at all it finds // something even as an unprivileged user. A machine with none -- a CI // runner -- legitimately finds nothing. log.info("enumerated {d} devices", .{seen});}
test "a scratch buffer below the floor is refused rather than overrun" { const io = std.testing.io; var too_small: [8]u8 = undefined; var devices: Enumerator = undefined; try std.testing.expectError( error.BufferTooSmall, devices.init(io, &too_small, .{}), );}
test "filtering on a vendor nothing has yields nothing" { const io = std.testing.io; var scratch: [recommended_scratch]u8 = undefined; var devices: Enumerator = undefined; // 0xFFFF is not an assigned USB vendor ID. try devices.init(io, &scratch, .{ .vendor_id = 0xFFFF }); defer devices.deinit(io); try std.testing.expectEqual(@as(?*const DeviceInfo, null), try devices.next(io));}
test { std.testing.refAllDecls(@This());}