Use Windows API generator

Author: manuelbl

java-does-usb/.mvn/wrapper/maven-wrapper.jar

@@ -15,7 +15,7 @@ The resulting code is then committed to the source code repository.
 
 - According to the jextract mailing list, it would be required to create separate code for Intel x64 and ARM64 architecture. And jextract would need to be run on each architecture separately (no cross-compilation). Fortunately, this doesn't seem to be the case. Linux code generated on Intel x64 also runs on ARM64 without change. The same holds for macOS. However, jextract needs to be run on each operating system separately.
 
-- The *Foreign Function And Memory* API has the abilitiy to save the thread-specific error values (`GetLastError()` on Windows, `errno` on Linux). This is required as the JVM calls operation system functions as well, which overwrite the result values. To save the values, an additional parameter must be added to function calls. Unfortunately, this is not supported by jextract. So a good number of function bindings have to be written manually.
+- The *Foreign Function And Memory* API has the abilitiy to save the thread-specific error values (`GetLastError()` on Windows, `errno` on Linux). This is required as the JVM calls operating system functions as well, which overwrite the result values. To save the values, an additional parameter must be added to function calls. Unfortunately, this is not supported by jextract. So a good number of function bindings have to be written manually.
 
 - *jextract* is not really transparent about what it does. It often skips elements without providing any information. In particular, it will silently skip a requested element in these cases:
 
@@ -53,22 +53,11 @@ Most of the required native functions on macOS are part of a framework. Framewor
 
 ## Windows
 
-Most Windows SDK header files are not independent. They require `Windows.h` to be included first. So instead of specifying the target header files directly, a helper header file (`windows_headers.h` in this directory) is specified.
-
-Compared to Linux and macOS, the code generation on Windows is very slow (about 1 min vs 3 seconds). And jextract crashes sometimes.
-
-The known limitations are:
-
-- Variable size `struct`: Several Windows struct are of variable size. The last member is an array. The `struct` definition specifies array length 1. But you are expected to allocate more space depending on the actual array size you need. *jextract* generates code for array length 1 and checks the length when the members are accessed. So the generated code is difficult to use. Variable size `struct`s are a pain - in any language.
-
-- GUID constants like `GUID_DEVINTERFACE_USB_DEVICE` do not work. While code is generated, the code fails at run-time as it is unable to locate the symbol. This is due to the fact that `GUID_DEVINTERFACE_USB_DEVICE` actually resolve to a variable definition and not to a variable declaration. The GUID constant is not contained in any library; instead the header files use linkage options to generate the constant in the callers code, which does not work with FFM. Such constants should be skipped by *jextract*.
-
-- *jextract* is a batch script and turns off *echo mode*. If a single batch scripts has multiple calls of *jextract*, two things need to be considered:
-
-    - If the regular command interpreter `cmd.exe` is used, *jextract* must be called using `call`, i.e. `call jextract header.h`.
-    - If *PowerShell* is used instead, `call` is not needed but *PowerShell* must be configured to allow the execution of scripts.
-    - *jextract* turns off *echo mode*. So the first call will behave differently than the following calls.
+The Windows code is not generated with _jextract_ but with [Windows API Generator](https://github.com/manuelbl/WindowsApiGenerator)
+instead. It is run as a Maven plugin. The generated code is not committed to GitHub.
 
+Windows API Generator supports call state capturing (`GetLastError()`), structs with a
+variable size, GUID and device property key (`DEVPKEY`) constants etc.
 
 
 ## Code Size

java-does-usb/.mvn/wrapper/maven-wrapper.properties

@@ -9,8 +9,8 @@
     <version>1.2.0</version>
 
     <properties>
-        <maven.compiler.source>22</maven.compiler.source>
-        <maven.compiler.target>22</maven.compiler.target>
+        <maven.compiler.source>23</maven.compiler.source>
+        <maven.compiler.target>23</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <sonar.exclusions>src/main/java/net/codecrete/usb/**/gen/**/*</sonar.exclusions>
     </properties>
@@ -52,14 +52,97 @@
 
     <build>
         <plugins>
+            <plugin>
+                <groupId>net.codecrete.windows-api</groupId>
+                <artifactId>windowsapi-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>windows-api</goal>
+                        </goals>
+                        <configuration>
+                            <functions>
+                                <function>CLSIDFromString</function>
+                                <function>CreateFileW</function>
+                                <function>CreateIoCompletionPort</function>
+                                <function>CreateWindowExW</function>
+                                <function>DefWindowProcW</function>
+                                <function>DeviceIoControl</function>
+                                <function>FormatMessageW</function>
+                                <function>GetMessageW</function>
+                                <function>GetModuleHandleW</function>
+                                <function>GetQueuedCompletionStatus</function>
+                                <function>LocalFree</function>
+                                <function>RegCloseKey</function>
+                                <function>RegQueryValueExW</function>
+                                <function>RegisterClassExW</function>
+                                <function>RegisterDeviceNotificationW</function>
+                                <function>SetupDiCreateDeviceInfoList</function>
+                                <function>SetupDiDeleteDeviceInterfaceData</function>
+                                <function>SetupDiDestroyDeviceInfoList</function>
+                                <function>SetupDiEnumDeviceInfo</function>
+                                <function>SetupDiEnumDeviceInterfaces</function>
+                                <function>SetupDiGetClassDevsW</function>
+                                <function>SetupDiGetDeviceInterfaceDetailW</function>
+                                <function>SetupDiGetDevicePropertyW</function>
+                                <function>SetupDiOpenDevRegKey</function>
+                                <function>SetupDiOpenDeviceInfoW</function>
+                                <function>SetupDiOpenDeviceInterfaceW</function>
+                                <function>WinUsb_AbortPipe</function>
+                                <function>WinUsb_Free</function>
+                                <function>WinUsb_GetAssociatedInterface</function>
+                                <function>WinUsb_Initialize</function>
+                                <function>WinUsb_ReadPipe</function>
+                                <function>WinUsb_ResetPipe</function>
+                                <function>WinUsb_SetCurrentAlternateSetting</function>
+                                <function>WinUsb_SetPipePolicy</function>
+                                <function>WinUsb_WritePipe</function>
+                            </functions>
+                            <structs>
+                                <struct>DEV_BROADCAST_DEVICEINTERFACE_W</struct>
+                                <struct>DEV_BROADCAST_HDR</struct>
+                                <struct>USB_DESCRIPTOR_REQUEST</struct>
+                                <struct>USB_NODE_CONNECTION_INFORMATION_EX</struct>
+                            </structs>
+                            <enumerations>
+                                <enumeration>DEV_BROADCAST_HDR_DEVICE_TYPE</enumeration>
+                                <enumeration>FORMAT_MESSAGE_OPTIONS</enumeration>
+                                <enumeration>GENERIC_ACCESS_RIGHTS</enumeration>
+                                <enumeration>REG_SAM_FLAGS</enumeration>
+                                <enumeration>SETUP_DI_PROPERTY_CHANGE_SCOPE</enumeration>
+                            </enumerations>
+                            <constants>
+                                <constant>DBT_DEVICEARRIVAL</constant>
+                                <constant>DBT_DEVICEREMOVECOMPLETE</constant>
+                                <constant>DEVPKEY_Device_Address</constant>
+                                <constant>DEVPKEY_Device_Children</constant>
+                                <constant>DEVPKEY_Device_HardwareIds</constant>
+                                <constant>DEVPKEY_Device_InstanceId</constant>
+                                <constant>DEVPKEY_Device_Parent</constant>
+                                <constant>DEVPKEY_Device_Service</constant>
+                                <constant>DIREG_DEV</constant>
+                                <constant>GUID_DEVINTERFACE_USB_DEVICE</constant>
+                                <constant>GUID_DEVINTERFACE_USB_HUB</constant>
+                                <constant>HWND_MESSAGE</constant>
+                                <constant>INFINITE</constant>
+                                <constant>IOCTL_USB_GET_DESCRIPTOR_FROM_NODE_CONNECTION</constant>
+                                <constant>IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX</constant>
+                                <constant>STATUS_UNSUCCESSFUL</constant>
+                                <constant>USB_REQUEST_GET_DESCRIPTOR</constant>
+                                <constant>WM_DEVICECHANGE</constant>
+                            </constants>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
                 <version>3.12.1</version>
                 <configuration>
-                    <release>22</release>
-                    <source>22</source>
-                    <target>22</target>
+                    <release>23</release>
+                    <source>23</source>
+                    <target>23</target>
                 </configuration>
             </plugin>
             <plugin>
@@ -129,6 +212,12 @@
                         <autoReleaseAfterClose>true</autoReleaseAfterClose>
                     </configuration>
                 </plugin>
+
+                <plugin>
+                    <groupId>net.codecrete.windows-api</groupId>
+                    <artifactId>windowsapi-maven-plugin</artifactId>
+                    <version>0.8.0</version>
+                </plugin>
             </plugins>
         </pluginManagement>
     </build>

java-does-usb/jextract/README.md

@@ -26,6 +26,7 @@
  */
 public class Usb {
 
+    @SuppressWarnings("java:S1192")
     private static UsbDeviceRegistry createInstance() {
         var osName = System.getProperty("os.name");
         var osArch = System.getProperty("os.arch");

java-does-usb/jextract/windows/gen_win.cmd

@@ -71,7 +71,9 @@ public interface UsbAlternateInterface {
      *
      * @return a list of endpoints.
      */
-    @NotNull @Unmodifiable List<UsbEndpoint> getEndpoints();
+    @NotNull
+    @Unmodifiable
+    List<UsbEndpoint> getEndpoints();
 
     /**
      * Gets the endpoint with the specified number and direction.

java-does-usb/jextract/windows/windows_headers.h

@@ -189,7 +189,9 @@ public interface UsbDevice {
      *
      * @return a list of USB interfaces
      */
-    @NotNull @Unmodifiable List<UsbInterface> getInterfaces();
+    @NotNull
+    @Unmodifiable
+    List<UsbInterface> getInterfaces();
 
     /**
      * Gets the interface with the specified number.
@@ -260,7 +262,7 @@ public interface UsbDevice {
     /**
      * Executes a control transfer request and optionally sends data.
      * <p>
-     * This method blocks until the device has acknowledge the request or an error has occurred.
+     * This method blocks until the device has acknowledged the request or an error has occurred.
      * </p>
      * <p>
      * The control transfer request is sent to endpoint 0. The transfer is expected to either have
@@ -390,7 +392,7 @@ public interface UsbDevice {
      * and the last packet size was equal to maximum packet size of the endpoint.
      * </p>
      * <p>
-     * If {@link #transferOut(int, byte[])} and a output stream or multiple output streams
+     * If {@link #transferOut(int, byte[])} and an output stream or multiple output streams
      * are used concurrently for the same endpoint, the behavior is unpredictable.
      * </p>
      *

java-does-usb/pom.xml

@@ -64,5 +64,7 @@ public interface UsbInterface {
      *
      * @return a list of the alternate settings
      */
-    @NotNull @Unmodifiable List<UsbAlternateInterface> getAlternates();
+    @NotNull
+    @Unmodifiable
+    List<UsbAlternateInterface> getAlternates();
 }