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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372// SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! An open HID device, and every operation on one.//!//! ```//! var dev: hidapi.Device = undefined;//! try dev.open(io, info.id, .{});//! defer dev.close(io);//!//! var buf: [64]u8 = undefined;//! const report = try dev.read(io, &buf);//! ```//!//! A `Device` is storage the caller owns and uses through a pointer, and it//! must not be moved between `open` and `close`. That is not the shape a//! two-word handle would want, and it is not negotiable: on macOS IOKit is//! handed this pointer at open time and calls back on it from another thread//! for the life of the device. One signature for all four backends is worth//! more than a smaller type on the three where it would fit.//!//! This is the portable half. It holds the conventions that are the same//! everywhere -- the report ID in the first byte, what an empty answer means,//! which errors callers see -- and forwards the system calls to the backend//! for the operating system being built for. `src/backend.zig` picks that//! backend and `src/backend/contract.zig` says what it has to provide.//!//! Every method takes a `std.Io` and dispatches its syscall through it rather//! than issuing it directly, which leaves the choice of how to wait up to the//! caller's `Io` implementation.//!//! **Every buffer here begins with the report ID**, which is `0x00` for a//! device that does not use numbered reports. A sixteen byte report is//! seventeen bytes of buffer. This is the convention the HID specification//! forces and every HID library shares; forgetting it is the single most//! common way to get a device to ignore you.
const Device = @This();
const std = @import("std");
const backend = @import("backend.zig");const errors = @import("errors.zig");const DeviceId = @import("DeviceId.zig");const DeviceInfo = @import("DeviceInfo.zig");
/// Backend state, inline, so that the library allocates nothing and the/// storage is the caller's.impl: backend.impl.Device,
/// How to open a device.pub const OpenOptions = struct { /// Backing store for input reports that arrive before the caller asks for /// one. /// /// Only macOS and Windows queue in user space and need it: on macOS /// reports arrive on a callback whether anyone is reading or not, and on /// Windows the class driver's own ring is what this replaces. Linux and /// FreeBSD let the kernel do it -- hidraw buffers 64 reports on both -- /// and ignore this entirely. /// /// `error.BufferTooSmall` if it cannot hold a single input report from the /// device being opened. input_queue: []u8 = &.{},
/// Working memory for rebuilding a report descriptor. /// /// Only Windows uses it, and only because Windows is the one system that /// does not keep the descriptor a device sent: the HID class driver /// parses it once and keeps its own form, so the descriptor has to be /// rebuilt from that. Doing so needs somewhere to work, and this library /// allocates nothing, so the somewhere is the caller's. /// /// Leave it empty and `getReportDescriptor` reports `error.Unsupported` /// on Windows, exactly as it did before. Sixteen kilobytes is comfortable /// for any device; see `Device.recommended_descriptor_scratch`. descriptor_scratch: []u8 = &.{},
/// Open the device exclusively, so that nothing else receives events from /// it while it is held. /// /// Off by default, which differs from the C hidapi: that library seizes /// the device on macOS for backward compatibility with its own history. /// Seizing stops the device working for everything else on the machine, /// and on a device the system has claimed it simply fails, so it is a /// thing to ask for rather than a thing to get. exclusive: bool = false,
/// How long a control transfer may take before it is abandoned. /// /// Only macOS reads this, where a synchronous IOKit call cannot be /// cancelled and a wedged device would otherwise hold a task forever. request_timeout: std.Io.Timeout = .{ .duration = .{ .raw = .fromSeconds(5), .clock = .awake }, },};
/// Open the device that `id` names, as an `Enumerator` reported it.////// Fails with `error.DeviceNotFound` when nothing answers to that ID -- which/// includes a device unplugged since it was enumerated -- and/// `error.AccessDenied` when the process may not talk to it, which is the/// usual answer for an unprivileged process on Linux and FreeBSD and for a/// keyboard or pointing device on Windows. The README says how to fix each.////// The caller owns the device and must `close` it.pub fn open( dev: *Device, io: std.Io, id: DeviceId, options: OpenOptions,) errors.OpenError!void { return dev.impl.open(io, id, options);}
/// Close the device. Errors are not reported, because there is nothing a/// caller could do about one.pub fn close(dev: *Device, io: std.Io) void { dev.impl.close(io);}
/// Read an input report, waiting until the device sends one.////// Input reports arrive on the interrupt IN endpoint. The first byte is the/// report ID if the device uses numbered reports.////// This waits indefinitely: a device that is simply idle, such as a mouse/// nobody is touching, never returns from it. Use `readTimeout` for anything/// that has to stay responsive, and cancel the task through `io` to stop a/// read that is already waiting.////// Returns `error.DeviceDisconnected` when the device goes away, which is the/// ordinary end of a read loop rather than a failure to report.pub fn read(dev: *Device, io: std.Io, buf: []u8) errors.ReadError![]u8 { return dev.impl.read(io, buf);}
/// Read an input report, giving up after `timeout`.////// Returns `null` when nothing arrived in time. Since `std.Io.Timeout` can be/// a zero duration, that also covers a non-blocking poll:////// ```/// // Block for at most 250 ms./// const report = try dev.readTimeout(io, &buf, .{/// .duration = .{ .raw = .fromMilliseconds(250), .clock = .awake },/// });////// // Take whatever is already waiting, and do not wait./// const now = try dev.readTimeout(io, &buf, .{/// .duration = .{ .raw = .zero, .clock = .awake },/// });/// ```////// There is deliberately no non-blocking *mode* to set, the way the C hidapi/// has one. A mode is a second way of saying what the timeout already says,/// and it is state every backend would have to honour on every read path.////// `null` and a zero-length report are different answers: a HID device may/// legitimately send a report with no data, so the two cannot share a/// representation. Taking a `Timeout` rather than a count of milliseconds/// matters for the same reason it does elsewhere in `std.Io` -- a caller/// polling several devices against one deadline says so once, instead of/// recomputing a remaining duration per device and drifting.pub fn readTimeout( dev: *Device, io: std.Io, buf: []u8, timeout: std.Io.Timeout,) errors.ReadError!?[]u8 { return dev.impl.readTimeout(io, buf, timeout);}
/// Write an output report.////// The first byte of `report` is the report ID, `0x00` for a device that does/// not use numbered reports. The report goes to the first OUT endpoint if the/// device has one, and over the control endpoint if it does not.pub fn write(dev: *Device, io: std.Io, report: []const u8) errors.WriteError!usize { return dev.impl.write(io, report);}
/// Send a feature report over the control endpoint.////// The first byte of `report` is the report ID.pub fn sendFeatureReport( dev: *Device, io: std.Io, report: []const u8,) errors.ReportError!usize { return dev.impl.sendFeatureReport(io, report);}
/// Request a feature report over the control endpoint.////// Set `buf[0]` to the report ID wanted. On return it is still there and the/// report data starts at `buf[1]`, so `buf` has to be one byte longer than the/// report.pub fn getFeatureReport(dev: *Device, io: std.Io, buf: []u8) errors.ReportError![]u8 { return dev.impl.getFeatureReport(io, buf);}
/// Request an input report over the control endpoint.////// Slower than `read` on any device with a dedicated IN endpoint, and useful/// for a different reason: it asks for a specific report by ID, which is how a/// program learns a device's initial state before it starts listening for/// changes.pub fn getInputReport(dev: *Device, io: std.Io, buf: []u8) errors.ReportError![]u8 { return dev.impl.getInputReport(io, buf);}
/// The size in bytes of the device's HID report descriptor.////// Returns `error.Unsupported` on Windows; see `getReportDescriptor`.pub fn getReportDescriptorLen(dev: *Device, io: std.Io) errors.DescriptorError!u32 { return dev.impl.getReportDescriptorLen(io);}
/// Copy the device's HID report descriptor into `buf`.////// Size `buf` with `getReportDescriptorLen`, or use/// `max_report_descriptor_len` to be sure it always fits.////// On Windows this is **rebuilt** rather than read, because the HID class/// driver does not keep the bytes the device sent. What comes back describes/// the same device -- same reports, same fields, same bit positions -- and is/// not byte-for-byte what the device sent, because the parsed form has lost/// where the padding was and how the items were grouped. Do not compare two/// descriptors for equality across platforms.////// Rebuilding needs working memory, so it happens only when the device was/// opened with `OpenOptions.descriptor_scratch`; without it the answer is/// `error.Unsupported`, as it is for a blob this library cannot read.pub fn getReportDescriptor( dev: *Device, io: std.Io, buf: []u8,) errors.DescriptorError![]const u8 { return dev.impl.getReportDescriptor(io, buf);}
/// Input reports thrown away because the queue was full, since this was last/// asked, resetting the count.////// Always zero on Linux, FreeBSD and Windows, where the kernel or the class/// driver does the queueing and this library never sees a full buffer. On/// macOS it is real: reports arrive on a callback whether anyone is reading or/// not, so a program that falls behind loses them.////// This exists because losing input silently is worse than losing it loudly./// The C hidapi caps its macOS queue at thirty reports and drops quietly,/// which turns "my program is too slow" into "my device is flaky".pub fn takeDroppedReports(dev: *Device) u64 { return dev.impl.takeDroppedReports();}
/// The largest report descriptor any device reports, so a buffer this size/// always holds one.pub const max_report_descriptor_len = backend.impl.max_report_descriptor_len;
/// A comfortable size for `OpenOptions.descriptor_scratch`.////// Zero on every backend but Windows, which is the only one that has to/// rebuild a descriptor rather than read it.pub const recommended_descriptor_scratch = backend.impl.recommended_descriptor_scratch;
/// Fill `out` with what the open device says about itself.////// This answers less than enumeration does, because it asks the HID device/// rather than the system: on Linux `manufacturer` is not reported here at all/// and `product` carries the vendor and product strings run together. A caller/// that wants the full picture should keep the `DeviceInfo` the `Enumerator`/// produced rather than re-reading it from the open device.pub fn getInfo( dev: *Device, io: std.Io, out: *DeviceInfo,) (errors.DeviceError || std.Io.Cancelable)!void { return dev.impl.getInfo(io, out);}
test { // `std.testing.refAllDecls` is not recursive, so the root module // referencing this file does not reach these functions. Referencing them // here is what makes the semantic analyzer check every method body, which // catches errors in methods that no test happens to call. std.testing.refAllDecls(@This());}
test "read-only operations against attached devices" { const io = std.testing.io; const Enumerator = @import("Enumerator.zig");
var scratch: [Enumerator.recommended_scratch]u8 = undefined; var devices: Enumerator = undefined; try devices.init(io, &scratch, .{}); defer devices.deinit(io);
var descriptor: [max_report_descriptor_len]u8 = undefined; var descriptor_scratch: [recommended_descriptor_scratch]u8 = undefined; var checked: usize = 0;
while (try devices.next(io)) |listed| { var dev: Device = undefined; // Enumeration needs no permission and opening does, so most devices // on an unprivileged run are listed and then refused. That is the // point of the split, and not a reason to fail the test. // // The scratch is what lets Windows rebuild a descriptor; the other // three ignore it. dev.open(io, listed.id, .{ .descriptor_scratch = &descriptor_scratch }) catch continue; defer dev.close(io);
// Only side-effect-free calls belong here, because this runs against // whatever hardware happens to be attached. `read` waits for a report // that an idle device never sends, and `write` and `sendFeatureReport` // change device state, so all three are covered by the reference // above only. var opened: DeviceInfo = undefined; try dev.getInfo(io, &opened);
// The device and the system have to agree about what it is. This is // the assertion that would catch the sysfs walk reading the wrong // parent, which is the one mistake in enumeration that produces // plausible answers rather than obvious ones. try std.testing.expectEqual(listed.vendor_id, opened.vendor_id); try std.testing.expectEqual(listed.product_id, opened.product_id); try std.testing.expectEqual(listed.native_bus, opened.native_bus);
// A device that cannot produce a descriptor at all -- on Windows, // one whose preparsed data this library cannot read -- is a correct // answer rather than a failure, but the two calls have to agree about // which answer they are giving. if (dev.getReportDescriptorLen(io)) |len| { try std.testing.expect(len <= max_report_descriptor_len); const bytes = try dev.getReportDescriptor(io, descriptor[0..len]); try std.testing.expectEqual(@as(usize, len), bytes.len);
// A buffer one byte short of the descriptor has to be reported // rather than quietly filled. if (len > 0) try std.testing.expectError( error.BufferTooSmall, dev.getReportDescriptor(io, descriptor[0 .. len - 1]), );
// Whatever the descriptor came from -- read from the kernel, or // rebuilt from Windows' parsed form -- it has to describe the // device the system said this was. On Windows this is the only // check the reconstruction gets against real hardware, since the // bytes the device actually sent are gone. if (@import("descriptor.zig").firstUsage(bytes)) |usage| { if (listed.usage_page != 0) { try std.testing.expectEqual(listed.usage_page, usage.page); try std.testing.expectEqual(listed.usage, usage.id); } } } else |err| switch (err) { error.Unsupported => try std.testing.expectError( error.Unsupported, dev.getReportDescriptor(io, &descriptor), ), else => return err, }
checked += 1; }
// Nothing attached, or no permission to open any of it. if (checked == 0) return error.SkipZigTest;}