Windows: Helpful error message if WinUSB driver not installed

manuelbl · Oct 13, 2024 · 0f1d2ef · 0f1d2ef
1 parent 0c8e5f2
commit 0f1d2ef
Show file tree

Hide file tree

Showing 5 changed files with 24 additions and 5 deletions.
diff --git a/java-does-usb/jextract/windows/gen_win.cmd b/java-does-usb/jextract/windows/gen_win.cmd
@@ -19,6 +19,7 @@ call %JEXTRACT% --output ../../src/main/java ^
   --include-constant ERROR_MORE_DATA ^
   --include-constant ERROR_INSUFFICIENT_BUFFER ^
   --include-constant ERROR_FILE_NOT_FOUND ^
+  --include-constant ERROR_INVALID_PARAMETER ^
   --include-constant ERROR_GEN_FAILURE ^
   --include-constant ERROR_NOT_FOUND ^
   --include-constant ERROR_IO_PENDING ^

diff --git a/java-does-usb/pom.xml b/java-does-usb/pom.xml
@@ -12,6 +12,7 @@
         <maven.compiler.source>22</maven.compiler.source>
         <maven.compiler.target>22</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <sonar.exclusions>src/main/java/net/codecrete/usb/**/gen/**/*</sonar.exclusions>
     </properties>
 
     <name>Java Does USB</name>

diff --git a/java-does-usb/src/main/java/net/codecrete/usb/UsbException.java b/java-does-usb/src/main/java/net/codecrete/usb/UsbException.java
@@ -37,7 +37,7 @@ public UsbException(@NotNull String message) {
      * @param errorCode the error code
      */
     public UsbException(@NotNull String message, int errorCode) {
-        super(message + " (error code:" + errorCode + ")");
+        super(message + " (error code: " + errorCode + ")");
         code = errorCode;
     }
 

diff --git a/java-does-usb/src/main/java/net/codecrete/usb/windows/WindowsUsbDevice.java b/java-does-usb/src/main/java/net/codecrete/usb/windows/WindowsUsbDevice.java
@@ -42,6 +42,7 @@
 import static net.codecrete.usb.windows.Win.allocateErrorState;
 import static net.codecrete.usb.windows.WindowsUsbException.throwException;
 import static net.codecrete.usb.windows.WindowsUsbException.throwLastError;
+import static net.codecrete.usb.windows.gen.kernel32.Kernel32.ERROR_INVALID_PARAMETER;
 
 /**
  * Windows implementation for USB device.
@@ -121,7 +122,7 @@ public void claimInterface(int interfaceNumber) {
         // retries might be needed until the device path is available.
         var numRetries = 30; // 30 x 100ms
         while (true) {
-            if (claimInteraceSynchronized(interfaceNumber))
+            if (claimInterfaceSynchronized(interfaceNumber))
                 return; // success
 
             numRetries -= 1;
@@ -139,7 +140,8 @@ public void claimInterface(int interfaceNumber) {
         }
     }
 
-    private synchronized boolean claimInteraceSynchronized(int interfaceNumber) {
+    @SuppressWarnings("java:S3776")
+    private synchronized boolean claimInterfaceSynchronized(int interfaceNumber) {
         checkIsOpen();
 
         getInterfaceWithCheck(interfaceNumber, false);
@@ -172,8 +174,14 @@ private synchronized boolean claimInteraceSynchronized(int interfaceNumber) {
                 try {
                     // open first interface
                     var interfaceHandleHolder = arena.allocate(ADDRESS);
-                    if (WinUSB2.WinUsb_Initialize(deviceHandle, interfaceHandleHolder, errorState) == 0)
+                    if (WinUSB2.WinUsb_Initialize(deviceHandle, interfaceHandleHolder, errorState) == 0) {
+                        if (Win.getLastError(errorState) == ERROR_INVALID_PARAMETER())
+                            throw new UsbException(
+                                    "claiming interface failed (required WinUSB driver is probably not installed for the device)",
+                                    ERROR_INVALID_PARAMETER()
+                            );
                         throwLastError(errorState, "claiming interface failed");
+                    }
                     var interfaceHandle = dereference(interfaceHandleHolder);
 
                     firstIntfHandle.deviceHandle = deviceHandle;
@@ -571,7 +579,7 @@ private String getChildDevicePath(String instanceId, int interfaceNumber) {
             var devicePath = deviceInfoSet.getDevicePathByGUID(instanceId);
             if (devicePath == null) {
                 LOG.log(INFO, "Child device {0} has no device path / interface GUID", instanceId);
-                throw new UsbException("claiming interface failed (function has no device path / interface GUID, might be missing WinUSB driver)");
+                throw new UsbException("claiming interface failed (composite function has no device path / interface GUID; the required WinUSB driver is probably not installed)");
             }
 
             if (devicePaths == null)

diff --git a/java-does-usb/src/main/java/net/codecrete/usb/windows/gen/kernel32/Kernel32.java b/java-does-usb/src/main/java/net/codecrete/usb/windows/gen/kernel32/Kernel32.java
@@ -390,6 +390,15 @@ public static int ERROR_FILE_NOT_FOUND() {
     public static int ERROR_GEN_FAILURE() {
         return ERROR_GEN_FAILURE;
     }
+    private static final int ERROR_INVALID_PARAMETER = (int)87L;
+    /**
+     * {@snippet lang=c :
+     * #define ERROR_INVALID_PARAMETER 87
+     * }
+     */
+    public static int ERROR_INVALID_PARAMETER() {
+        return ERROR_INVALID_PARAMETER;
+    }
     private static final int ERROR_INSUFFICIENT_BUFFER = (int)122L;
     /**
      * {@snippet lang=c :