feat: expose macOS exclusive device open mode (#24)

* feat: expose macOS exclusive device open mode

Add hidDarwinSetOpenExclusive and hidDarwinGetOpenExclusive wrappers
for the macOS-specific hid_darwin_set_open_exclusive and
hid_darwin_get_open_exclusive functions. On non-macOS platforms the
wrappers catch the missing-symbol error and return safe defaults.

* ci: add macOS test runner and skip darwin tests on Linux

Platform-specific darwin exclusive mode tests now skip on non-macOS.
Add a test-macos CI job so those tests still run on every push/PR.

Author: repentsinner

.github/workflows/ci.yml

@@ -22,3 +22,13 @@ jobs:
       - run: dart analyze --fatal-infos
       - run: dart format --output=none --set-exit-if-changed .
       - run: dart test
+
+  test-macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dart-lang/setup-dart@v1
+        with:
+          sdk: '3.10.0'
+      - run: dart pub get
+      - run: dart test

SPEC.md

@@ -109,7 +109,36 @@ let release-please derive the correct version bump automatically.
 
 ---
 
-## 6. Publishing
+## 6. macOS exclusive device access
+
+*Status: in progress*
+
+On macOS, hidapi defaults to opening devices in exclusive mode
+(`kIOHIDOptionsTypeSeizeDevice`). This is set by `hid_init()` calling
+`hid_darwin_set_open_exclusive(1)` for backward compatibility.
+
+Exclusive mode prevents a second `hid_open_path` call on the same device
+path within the same process — the `IOHIDDeviceOpen` call fails. This
+breaks applications that open separate read and write handles from
+different Dart isolates (isolates share process memory, so the C-level
+`device_open_options` global is visible to all threads).
+
+The package shall expose the macOS-specific exclusive mode control:
+
+- `hidDarwinSetOpenExclusive(bool exclusive)` — sets the global open mode.
+  No-op on Linux and Windows where the symbol does not exist.
+- `hidDarwinGetOpenExclusive()` — returns the current setting.
+  Returns `false` on non-macOS platforms.
+
+The FFI bindings file shall include `hid_darwin_set_open_exclusive` and
+`hid_darwin_get_open_exclusive`. The Dart wrappers shall guard calls with
+a platform check (attempt the native call; catch the symbol-not-found
+error on non-macOS) so that consuming code does not need conditional
+imports.
+
+---
+
+## 7. Publishing
 
 *Status: not started*
 

lib/hidapi.dart

@@ -398,6 +398,32 @@ String hidVersionStr() {
   return ptr.cast<Utf8>().toDartString();
 }
 
+/// Set the macOS exclusive device open mode.
+///
+/// When `true`, subsequent [hidOpen] and [hidOpenPath] calls seize the device
+/// exclusively (`kIOHIDOptionsTypeSeizeDevice`). Defaults to `true` after
+/// [hidInit].
+///
+/// No-op on Linux and Windows where the symbol does not exist.
+void hidDarwinSetOpenExclusive(bool exclusive) {
+  try {
+    ffi.hid_darwin_set_open_exclusive(exclusive ? 1 : 0);
+  } on ArgumentError {
+    // Symbol not available on this platform.
+  }
+}
+
+/// Get the current macOS exclusive device open mode.
+///
+/// Returns `false` on non-macOS platforms where the symbol does not exist.
+bool hidDarwinGetOpenExclusive() {
+  try {
+    return ffi.hid_darwin_get_open_exclusive() != 0;
+  } on ArgumentError {
+    return false;
+  }
+}
+
 // --- Internal helpers ---
 
 HidDeviceInfo _deviceInfoFromNative(ffi.hid_device_info info) {

lib/src/hidapi_bindings.g.dart

@@ -202,3 +202,11 @@ external Pointer<hid_api_version> hid_version();
 
 @Native<Pointer<Char> Function()>()
 external Pointer<Char> hid_version_str();
+
+// --- macOS-only (hidapi_darwin.h) ---
+
+@Native<Void Function(Int32)>()
+external void hid_darwin_set_open_exclusive(int openExclusive);
+
+@Native<Int32 Function()>()
+external int hid_darwin_get_open_exclusive();

test/hidapi_test.dart

@@ -1,4 +1,5 @@
 import 'dart:ffi';
+import 'dart:io' show Platform;
 
 import 'package:ffi/ffi.dart';
 import 'package:hidapi/hidapi.dart';
@@ -87,4 +88,55 @@ void main() {
       }
     });
   });
+
+  group('darwin exclusive mode', () {
+    test('hidDarwinGetOpenExclusive returns bool', () {
+      hidInit();
+      try {
+        final val = hidDarwinGetOpenExclusive();
+        expect(val, isA<bool>());
+      } finally {
+        hidExit();
+      }
+    });
+
+    test('hidDarwinSetOpenExclusive accepts bool without throwing', () {
+      hidInit();
+      try {
+        expect(() => hidDarwinSetOpenExclusive(false), returnsNormally);
+      } finally {
+        hidExit();
+      }
+    });
+
+    test(
+      'hidDarwinSetOpenExclusive round-trips value',
+      () {
+        hidInit();
+        try {
+          hidDarwinSetOpenExclusive(false);
+          expect(hidDarwinGetOpenExclusive(), isFalse);
+          hidDarwinSetOpenExclusive(true);
+          expect(hidDarwinGetOpenExclusive(), isTrue);
+        } finally {
+          hidExit();
+        }
+      },
+      skip: !Platform.isMacOS ? 'macOS-only' : null,
+    );
+
+    test(
+      'hidDarwinGetOpenExclusive defaults to true after init',
+      () {
+        hidInit();
+        try {
+          // Per upstream docs, hid_init sets exclusive mode to true.
+          expect(hidDarwinGetOpenExclusive(), isTrue);
+        } finally {
+          hidExit();
+        }
+      },
+      skip: !Platform.isMacOS ? 'macOS-only' : null,
+    );
+  });
 }