Merge pull request #204 from anagnorisis2peripeteia/docs/programmatic-api

docs: add programmatic integration (IOCTL API) to README

Author: nefarius

DEVELOPER.md

@@ -0,0 +1,25 @@
+# HidHide Developer Guide
+
+## Programmatic integration
+
+Applications that need to communicate with *HidHide* at runtime can do so through a WDM control device that the driver
+exposes under the symbolic link `\\.\HidHide` (DOS device name). The same device can alternatively be opened by the
+interface GUID `{0C320FF7-BD9B-42B6-BDAF-49FEB9C91649}` via `SetupDiGetClassDevs` or `CM_Get_Device_Interface_List`.
+
+Once opened, the device accepts a set of I/O control codes constructed with `CTL_CODE(32769, N, METHOD_BUFFERED,
+FILE_READ_DATA)`. Function numbers 2048 through 2055 correspond to the get and set operations for the whitelist,
+blacklist, active state, and whitelist-inverse flag respectively. List payloads are exchanged as `MULTI_SZ` buffers —
+a sequence of null-terminated wide-character strings with an additional null terminator to close the list — and the
+buffer size supplied to `DeviceIoControl` must be an even number of bytes and include all terminators. Device instance
+paths should be in the format returned by `SetupDiGetDeviceInstanceId`, for example
+`HID\VID_054C&PID_09CC&MI_03\7&...`.
+
+Functions 2056 and 2057 expose the *session blacklist*, which is intended for feeder applications — programs that
+exclusively own one or more physical devices and re-expose them as virtual controllers. Unlike the persistent blacklist
+managed through functions 2050 and 2051, session blacklist entries live only in kernel memory and are never written to
+the registry, leaving the user's permanent *HidHide* configuration untouched. Each entry is owned by the process that
+issued the `ADD_SESSION_BLACKLIST` request. When that process exits for any reason — clean shutdown, crash, or forced
+termination — the driver automatically removes all of its entries within its process-notify callback registered via
+`PsSetCreateProcessNotifyRoutine`, so no cleanup code is required in the application. On a clean exit one may optionally issue `CLR_SESSION_BLACKLIST` to release the
+devices immediately, but this is not required. This approach is preferable to temporarily mutating the persistent
+blacklist because it requires no rollback logic and is inherently safe against unexpected termination.

README.md

@@ -102,6 +102,8 @@ Third-party software deployment may benefit from the *HidHide Command Line Inter
 Please be conservative while altering a clients' configuration and only extend the configuration with new features offered.
 Don't assume exclusive ownership of the configuration settings as a recovery typically requires manual actions by the user.
 
+See [DEVELOPER.md](DEVELOPER.md) for programmatic integration (IOCTL API) details for feeder applications.
+
 ## Bugs & Features
 
 ~~Found a bug and want it fixed? Feel free to open a detailed issue on the [GitHub issue tracker](../../issues)!~~