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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122// SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! What names a HID device to the operating system, and the only thing//! `Device.open` needs.//!//! The contents are the backend's business and no portable code should parse//! them. What each one puts here://!//! | Backend | Contents |//! | --- | --- |//! | Linux, FreeBSD | the device node path, `/dev/hidraw3` |//! | macOS | the registry entry ID, `DevSrvsID:4294970234` |//! | Windows | the device interface path, `\\?\HID#VID_046D&PID_C52B&...` |//!//! This is a value and not a slice, which is the whole point of it: an//! identifier's actual job is to be remembered -- copied into a configuration//! struct, printed, compared, read back off a command line -- and every one of//! those is free on a value and needs a lifetime rule on a slice. It is also//! what lets an ID outlive the `Enumerator` that produced it, which is the//! normal way a program picks a device once and opens it later.//!//! None of the four backends survives a replug: the node number, the registry//! entry ID and the interface path all change when hardware comes and goes.//! Code that has to recognise the same physical device across a replug should//! match on `DeviceInfo.serial_number`.
const DeviceId = @This();
const std = @import("std");
/// The longest identifier any backend produces.////// The bound comes from Windows, which is far and away the longest: `\\?\`/// plus a device instance ID, which `MAX_DEVICE_ID_LEN` caps at 200/// characters, plus `#` and a 38 character GUID, so about 243. Device/// interface paths use a restricted character set that encodes to one byte/// per UTF-16 unit, so that is 243 bytes and not three times as many. This is/// that bound doubled, which absorbs a nonconforming bus driver without/// reaching for a heap.pub const max_len = 512;
bytes: [max_len]u8,len: u16,
/// An ID naming nothing, which `Device.open` rejects with/// `error.DeviceNotFound`.pub const none: DeviceId = .{ .bytes = undefined, .len = 0 };
/// Build an ID from bytes a backend produced.pub fn init(text: []const u8) error{DeviceIdTooLong}!DeviceId { if (text.len > max_len) return error.DeviceIdTooLong; var self: DeviceId = .{ .bytes = undefined, .len = @intCast(text.len) }; @memcpy(self.bytes[0..text.len], text); return self;}
/// The identifier, aliasing `self`. Valid as long as the `DeviceId` is.pub fn slice(self: *const DeviceId) []const u8 { return self.bytes[0..self.len];}
/// Whether two IDs name the same device.////// Byte equality, because every backend produces its IDs one way and there is/// no case folding or normalisation that would be correct on all four. Two IDs/// from different enumerations of an unchanged system compare equal.pub fn eql(a: *const DeviceId, b: *const DeviceId) bool { return std.mem.eql(u8, a.slice(), b.slice());}
/// Print the identifier as the backend spelled it, so that what a program logs/// is what `parse` accepts back.pub fn format(self: *const DeviceId, w: *std.Io.Writer) std.Io.Writer.Error!void { try w.writeAll(self.slice());}
/// Read back an identifier that was printed or stored.////// Nothing is validated beyond the length: whether the device still exists,/// and whether the string was ever an identifier on this system at all, are/// questions only `Device.open` can answer.pub fn parse(text: []const u8) error{DeviceIdTooLong}!DeviceId { return init(text);}
test "round trips through format and parse" { const original: DeviceId = try .init("/dev/hidraw3");
var buf: [max_len]u8 = undefined; const printed = try std.fmt.bufPrint(&buf, "{f}", .{&original}); try std.testing.expectEqualStrings("/dev/hidraw3", printed);
const parsed: DeviceId = try .parse(printed); try std.testing.expect(original.eql(&parsed));}
test "a Windows interface path fits with room to spare" { // A real one, from a Logitech receiver. The longest field is the instance // ID in the middle, which is what `max_len` is sized against. const path = "\\\\?\\HID#VID_046D&PID_C52B&MI_01&Col01#8&1e78b1e2&0&0000" ++ "#{4d1e55b2-f16f-11cf-88cb-001111000030}"; const id: DeviceId = try .init(path); try std.testing.expectEqualStrings(path, id.slice()); try std.testing.expect(id.len < max_len / 2);}
test "too long is an error rather than a truncation" { const long: [max_len + 1]u8 = @splat('x'); try std.testing.expectError(error.DeviceIdTooLong, DeviceId.init(&long));}
test "the empty id compares unequal to a real one" { const real: DeviceId = try .init("/dev/hidraw0"); try std.testing.expect(!none.eql(&real)); try std.testing.expectEqual(@as(usize, 0), none.slice().len);}
test { std.testing.refAllDecls(@This());}