Added GetRawInputDeviceList definition and utility to User32 interface

Author: Lyor Goldstein

CHANGES.md

@@ -51,6 +51,7 @@ Features
 * [#481] (https://github.com/twall/jna/pull/481): Added volume management functions to 'com.sun.jna.platform.win32' - [@lgoldstein](https://github.com/lgoldstein).
 * [#483] (https://github.com/twall/jna/pull/483): Found and fixed duplicate method definitions for the same API in 'com.sun.jna.platform.win32' - [@lgoldstein](https://github.com/lgoldstein).
 * [#485] (https://github.com/twall/jna/pull/485): Implemented Comparable interface for many of the base types in 'com.sun.jna.platform.win32.WinDef' - [@lgoldstein](https://github.com/lgoldstein).
+* [#488] (https://github.com/twall/jna/pull/488): Added GetRawInputDeviceList definition and utility to 'com.sun.jna.platform.win32' User32 and User32Util - [@lgoldstein](https://github.com/lgoldstein).
 
 Bug Fixes
 ---------

contrib/platform/src/com/sun/jna/platform/win32/User32.java

@@ -1983,4 +1983,28 @@ long SendMessageTimeout(HWND hWnd, int msg, long wParam, long lParam,
 	 *         error information, call {@link Kernel32#GetLastError()}.
 	 */
 	long GetClassLongPtr(HWND hWnd, int nIndex);
+
+	/**
+	 * @param pRawInputDeviceList
+	 *            An array of {@link RAWINPUTDEVICELIST} structures for the devices
+	 *            attached to the system. If (@code null}, the number of devices is
+	 *            returned in <tt>puiNumDevices</tt>
+	 * @param puiNumDevices
+	 *            If <tt>pRawInputDeviceList</tt> is {@code null}, the function populates
+	 *            this variable with the number of devices attached to the system;
+	 *            otherwise, this variable specifies the number of {@link RAWINPUTDEVICELIST}
+	 *            structures that can be contained in the buffer to which <tt>pRawInputDeviceList</tt>
+	 *            points. If this value is less than the number of devices attached to
+	 *            the system, the function returns the actual number of devices in this
+	 *            variable and fails with ERROR_INSUFFICIENT_BUFFER.
+	 * @param cbSize
+	 *            The size of a {@link RAWINPUTDEVICELIST} structure, in bytes.
+	 * @return If the function is successful, the return value is the number of devices
+	 *             stored in the buffer pointed to by <tt>pRawInputDeviceList</tt>. On
+	 *             any other error, the function returns -1 and {@code GetLastError}
+	 *             returns the error indication.
+	 * @see RAWINPUTDEVICELIST#sizeof()
+	 * @see <A HREF="https://msdn.microsoft.com/en-us/library/windows/desktop/ms645598(v=vs.85).aspx">GetRawInputDeviceList</A>
+	 */
+	int GetRawInputDeviceList(RAWINPUTDEVICELIST[] pRawInputDeviceList, IntByReference puiNumDevices, int cbSize);
 }

contrib/platform/src/com/sun/jna/platform/win32/User32Util.java

@@ -9,11 +9,16 @@
  */
 
 package com.sun.jna.platform.win32;
+import java.util.Arrays;
+import java.util.List;
+
 import com.sun.jna.WString;
 import com.sun.jna.platform.win32.WinDef.HINSTANCE;
 import com.sun.jna.platform.win32.WinDef.HMENU;
 import com.sun.jna.platform.win32.WinDef.HWND;
 import com.sun.jna.platform.win32.WinDef.LPVOID;
+import com.sun.jna.platform.win32.WinUser.RAWINPUTDEVICELIST;
+import com.sun.jna.ptr.IntByReference;
 
 
 /**
@@ -48,4 +53,28 @@ public static final void destroyWindow(final HWND hWnd) {
         if (!User32.INSTANCE.DestroyWindow(hWnd))
             throw new Win32Exception(Kernel32.INSTANCE.GetLastError());
     }
+
+    public static final List<RAWINPUTDEVICELIST> GetRawInputDeviceList() {
+        IntByReference puiNumDevices = new IntByReference(0);
+        RAWINPUTDEVICELIST placeholder = new RAWINPUTDEVICELIST();
+        int cbSize = placeholder.sizeof();
+        // first call is with NULL so we query the expected number of devices
+        int returnValue = User32.INSTANCE.GetRawInputDeviceList(null, puiNumDevices, cbSize);
+        if (returnValue != 0) {
+            throw new Win32Exception(Kernel32.INSTANCE.GetLastError());
+        }
+
+        int deviceCount = puiNumDevices.getValue();
+        RAWINPUTDEVICELIST[] records = (RAWINPUTDEVICELIST[]) placeholder.toArray(deviceCount);
+        returnValue = User32.INSTANCE.GetRawInputDeviceList(records, puiNumDevices, cbSize);
+        if (returnValue == (-1)) {
+            throw new Win32Exception(Kernel32.INSTANCE.GetLastError());
+        }
+
+        if (returnValue != records.length) {
+            throw new IllegalStateException("Mismatched allocated (" + records.length + ") vs. received devices count (" + returnValue + ")");
+        }
+
+        return Arrays.asList(records);
+    }
 }

contrib/platform/src/com/sun/jna/platform/win32/WinNT.java

@@ -1240,6 +1240,11 @@ public void setPointer(Pointer p) {
 
             super.setPointer(p);
         }
+
+        @Override
+        public String toString() {
+            return String.valueOf(getPointer());
+        }
     }
 
     /**