Compare commits

...
Author SHA1 Message Date
poli0981 0378b7dfa2 Merge main (#466 squashed) into feat/input-reader: the trees are the same below this branch's own commits 2026-11-14 23:04:44 +07:00
poli0981andClaude Fable 5.2 5d6434c360 feat(input): a session can store what it was played with - schema 0024, the .partial file's chunk 11, both tiers (D160) (#466)
* feat(input): the arithmetic of controller statistics - classes, batteries, makers, one pad seen twice (D155-D163)

Nothing reads a device yet. Domain.Input says whether an XInput state or a DualSense report is a pad in use and what
its battery is, adds a battery's readings up, counts switches and decides when two entries are one pad;
Application.Input holds one session's slices and turns them into a reading a second; InputSessionBuilder turns a
session's readings into its totals, its controllers as JSON and its timeline. TelemetrySample can carry a reading.

Every byte and reading under test was written by hand: no report from a real controller has passed through this code.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* feat(input): a session can store what it was played with - schema 0024, the .partial file's chunk 11, both tiers (D160)

Nine columns on sessions (the time in front and its four classes, the switches of method, the sources that answered,
the controllers as JSON) and three on games (what a store lists of controller support), ADD COLUMN only. The .partial
file gains chunk 11, so a session recovered after the Agent died keeps its readings. SessionFinalizer.Build stores
them before the tier branch: hooked, unhooked and recovered sessions alike. The input series are sensor_blobs rows
named input.*, which the sensors' read now leaves out and FindInputSensorsAsync returns.

Nothing produces a reading yet. A ledger this build has opened cannot be opened by 0.1.0-beta.49 or earlier.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* fix(input): an arm of XInputPad.Battery's switch said what the default says (Qodana, on #464 after it merged)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* test(input): no using that makes the file's own qualified names redundant (InspectCode)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 16:02:29 +00:00
poli0981 102dcdd3f1 Merge feat/input-storage (main at 1d1d4ff) into feat/input-reader 2026-11-14 22:52:58 +07:00
poli0981andClaude Fable 5.2 f7129807e6 test(input): what InspectCode reported in the reader's tests - redundant casts, a hub disposed twice, a suppression not needed
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 22:20:52 +07:00
poli0981 be96564a8f Merge feat/input-storage (the inspection fix) into feat/input-reader 2026-11-14 22:19:55 +07:00
poli0981 80155d7638 Merge feat/input-storage (main at 8f24854, the Qodana fix) into feat/input-reader 2026-11-14 22:14:22 +07:00
poli0981andClaude Fable 5.2 e2675cd91c feat(input): the input reader, which the Agent does not start yet - raw input for controllers, XInput, the time of the last input (D155, D158, D159)
Application.Input.InputReader takes a slice about ten times a second from Infrastructure.Input.Win32InputBackend, on
the thread of InputDeviceHub, which exists only while a session has a view of it. It opens no device, sends nothing
to one and registers for no keyboard or mouse. tools/input-readonly-check.ps1 holds its Windows calls to a list.

With no controller at hand, what the reader does with one connected is not established.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 22:12:33 +07:00
26 changed files with 3132 additions and 8 deletions

No files matched your search

+10
View File
@@ -51,6 +51,16 @@ numeric core and does not move; the heading is the full version — corrected 20
stores them for hooked and unhooked sessions alike; the input series are `sensor_blobs` rows named `input.*`, which
the sensors' read leaves out. Nothing produces a reading yet. **A ledger this build has opened cannot be opened by
0.1.0-beta.49 or earlier.**
- **For developers: the input reader, which the Agent does not start yet** (D155, D158, D159; `docs/21_INPUT_DEVICES.md`
§The reader). `Application.Input.InputReader` takes a slice about ten times a second from
`Infrastructure.Input.Win32InputBackend` — raw input for joysticks and gamepads delivered to a window that is never
shown, three of XInput's getters, the time of the last keyboard or mouse input, the window in front — on the thread
of `InputDeviceHub`, which exists only while a session has a view of it. It opens no device, sends nothing to one,
and registers for no keyboard or mouse. A new gate, `tools/input-readonly-check.ps1`, holds the reader's Windows
calls to a committed list and refuses, on the list or off it, a call that sends to a device, injects input or reads
a key; no other managed source and no native source may name an input function. **With no controller at hand, what
the reader does with one connected is not established**: its tests use a Windows whose answers they write, and one
suite runs it on the real Windows of the machine and asserts only that it opens, answers and closes.
### Changed
+5 -1
View File
@@ -208,7 +208,11 @@ tools/ # accuracy-check, changelog-check, chokepoint-che
# the two on overlay-nvapi-allowed.txt),
# overlay-fields-check (D116, 2026-11-12: every member of a vendor's struct the
# Overlay reads for Advanced metrics is in fl_adv_fields.h and on
# overlay-allowed-fields.txt; a camera's position, axes and matrices nowhere)
# overlay-allowed-fields.txt; a camera's position, axes and matrices nowhere),
# input-readonly-check (D155-D163, 2026-11-14: every Windows function the input reader
# calls is declared in Infrastructure/Input/Win32Input.cs and on input-allowed-calls.txt;
# none sends to a device, injects input or reads a key; raw input is registered for
# joysticks and gamepads only; no native source names an input function)
# (six names added 2026-10-04)
# (PowerShell). This line used to name three, one of which
# — resx-audit — ~~does not exist~~ exists since 2026-09-13 with
+9
View File
@@ -499,6 +499,15 @@ function Invoke-ProjectGates {
Invoke-Checked 'overlay-fields-check (self-test)' { & $fieldsTool -SelfTest }
Invoke-Checked 'overlay-fields-check' { & $fieldsTool -RepoRoot $repo }
# 2026-11-14 (D155-D163): what is asked of Windows about controllers, the keyboard and the mouse. The reader's
# calls are declared in one file and held to tools/input-allowed-calls.txt in both directions; a call that sends to
# a device, injects input or reads a key is red even when the list names it; no managed source outside the reader
# and no native source names an input function; raw input is registered for joysticks and gamepads only. Text only.
Write-Step 'input-readonly-check'
$inputTool = Join-Path $repo 'tools/input-readonly-check.ps1'
Invoke-Checked 'input-readonly-check (self-test)' { & $inputTool -SelfTest }
Invoke-Checked 'input-readonly-check' { & $inputTool -RepoRoot $repo }
Write-Step 'docs-split-check'
$splitTool = Join-Path $repo 'tools/docs-split-check.ps1'
Invoke-Checked 'docs-split-check (self-test)' { & $splitTool -SelfTest }
+1
View File
@@ -411,6 +411,7 @@ Seven self-test cases, both directions; `./tools/notice-check.ps1 -Fix` writes a
14. `tools/changelog-check.ps1 -SelfTest` — nine cases, five expected RED. The live half needs a pull request's changed-file list and is supplied by `ci.yml`
14b. `tools/release-notes.ps1 -SelfTest` — five cases over a fixture changelog (a dated and an undated section, a missing one, a prefix that must not match, an empty one), and since beta.24 three over a temporary tree: a version with its own `docs/changelog/<version>.md` is read from it, one without from `CHANGELOG.md`, a prefix of a file name is not that file. The live half needs a tag's version and runs in `release.yml`, where a missing or empty section is a red release (P4 PR-5)
14e. **`tools/nvapi-readonly-check.ps1 -SelfTest`, then live** (owner decision D108, 2026-11-11) — every `NvAPI_*` call in `src/native/FrameLedger.NvapiBridge/src/fl_nvapi_bridge.cpp`, the one translation unit that links `nvapi64.lib` into a shipped binary, is on `tools/nvapi-allowed-calls.txt` and every name there is called; a name that sets, saves, restores, deletes, registers, resets, enables, disables or controls something is red **even when the list names it**, and so is one that returns an identifier (D104) — three reads the verb rule would refuse are exempt by name, each with its reason. Comments and string literals are taken out first, so a setter named in the comment that says it is never called is not a call. Seventeen self-test cases, both directions. Text only: it runs with or without the native build. `18_GPU_VENDOR_APIS` §Runtime policy's "never call a setter", which was a sentence until the bridge went from fourteen calls to forty-four
14g. **`tools/input-readonly-check.ps1 -SelfTest`, then live** (owner decisions D155–D163, 2026-11-14) — what FrameLedger asks Windows about controllers, the keyboard and the mouse. Every Windows function the input reader calls is declared in ONE file, `src/FrameLedger.Infrastructure/Input/Win32Input.cs`, and is on `tools/input-allowed-calls.txt`; every name there is declared; a name that sends to a controller (`XInputSetState`, any `HidD_*`), injects input (`SendInput`), reads a key (`GetAsyncKeyState`, `GetKeyState`, `GetKeyboardState`, `XInputGetKeystroke`) or installs a hook is red **even when the list names it**; no managed source outside `src/FrameLedger.Infrastructure/Input/` names an input function at all, and `NativeMethods.txt` asks CsWin32 for none; raw input is registered for joysticks and gamepads only — `InputReader.RegisteredUsages` is exactly usage page 1, usages 4 and 5, and the backend builds its registration from it and writes no usage as a number; and **no native source names an input function** — nothing loaded into a game reads input. Comments and string literals are taken out first. Seventeen self-test cases, both directions. Text only; it does not look at the tests, which may drive a real keyboard for the App's own shortcuts. `21_INPUT_DEVICES` §What is never read, which the Privacy Policy repeats to the user
14f. **`tools/overlay-fields-check.ps1 -SelfTest`, then live** (owner decision D116, 2026-11-12) — the same for the code loaded into a game: every member of a vendor's struct the Overlay reads for Advanced metrics is read in ONE header, `src/native/FrameLedger.Overlay/include/fl_adv_fields.h`, through parameters with fixed names, and is on `tools/overlay-allowed-fields.txt`; every name there is read; the parameters are not aliased and `->` reaches nothing but `desc` and the Overlay's own `region`; no other Overlay or Vulkan-layer source reads a listed member; **a camera's position, axes and matrices** (`cameraPos`, `cameraUp`, `cameraRight`, `cameraFwd`, the five matrices, `cameraPinholeOffset`, `cameraPosition`, `cameraForward`) **are named nowhere in those sources and not on the list, whatever the list says**; and neither `sl::Constants` nor `ffxDispatchDescFrameGenerationPrepareV2` is copied by value or measured with `sizeof`. Comments and string literals are taken out first. Nineteen self-test cases, both directions. Text only. It reads names, not types — which struct version carries a member is `17_HOOK_ENGINE` §Which struct version carries which field and ctest `fl_adv_fields`
14d. **`tools/docs-split-check.ps1 -SelfTest`, then live** (beta.24, owner decision D66) — `CHANGELOG.md` holds no released section beside `[Unreleased]`; each `docs/changelog/<version>.md` holds one `## ` heading, its own `## [<version>] - date`, and no relative link (the App renders release notes as `CHANGELOG.md`); `CHANGELOG.md` and the files under `docs/changelog/`, and `docs/HANDOFF.md` and the files under `docs/handoff/` — and since PR-5 `docs/20_OPEN_QUESTIONS.md` and `docs/open-questions/`, `docs/spike-notes.md` and `docs/spike-notes/` — name each other in both directions. Eleven self-test cases, both directions
14c. **`tools/buildid-check.ps1 -SelfTest`** (beta.18) — eight cases, both directions: a binary built from a dirty tree (`-dirty`, or the short form's `+`), one with no id, a missing one, and an expected id that is dirty or not an id are red. The live half needs the release's clean-checkout id and runs in `release.yml` over the published tree (§Release-time token substitution)
+54 -7
View File
@@ -4,11 +4,12 @@ What FrameLedger reads about game controllers and about the keyboard and mouse,
The numbers a session makes of it are in [`03_METRICS.md`](03_METRICS.md) §Input; the columns are in
[`06_DATA_MODEL.md`](06_DATA_MODEL.md).
> **Status, 2026-11-14 — nothing reads a device yet.** The model and the arithmetic exist (`FrameLedger.Domain.Input`,
> `FrameLedger.Application.Input`, `Application.Recording.InputSessionBuilder`), under tests whose every byte and
> reading was written by hand; and a session can store what it is given — schema 0024, the `.partial` file's chunk
> 11, the finalizer for both tiers (`06_DATA_MODEL`). The reader, the switch and the screens come in the pull
> requests after it, and this note is rewritten by each. **No report from a real controller has passed through any of this code**
> **Status, 2026-11-14 — the reader exists and the Agent does not start it yet.** The model and the arithmetic
> (`FrameLedger.Domain.Input`, `FrameLedger.Application.Input`, `Application.Recording.InputSessionBuilder`), the
> storage (schema 0024, the `.partial` file's chunk 11, the finalizer for both tiers — `06_DATA_MODEL`) and the reader
> itself (`Application.Input.InputReader`, `Infrastructure.Input`) are written and under test. Nothing composes the
> reader into the Agent: the switch, the terms and the screens come in the pull requests after this one, and this
> note is rewritten by each. **No report from a real controller has passed through any of this code**
> (owner decision D157): the developer has no controller, and what happens on a real one is owner-only item 48.
## The owner's request and decisions (2026-11-14)
@@ -36,8 +37,7 @@ Everything is a Windows API in a library Windows ships. **No third-party library
| Source | What it gives | Why this one |
|---|---|---|
| Raw Input (`RegisterRawInputDevices`, usage page 1, usages 4 and 5, `RIDEV_INPUTSINK \| RIDEV_DEVNOTIFY`) | the reports game controllers send, while the Agent is in the background; a controller arriving and leaving; its vendor and product ids | the documented way to receive a HID controller's reports without being in front, and it opens no handle to the device |
| `hid.dll`'s parser (`HidP_GetCaps`, `HidP_GetUsages`, `HidP_GetUsageValue`) | which usages of a report are set | a parser, not I/O: it reads the bytes Raw Input handed over |
| Raw Input (`RegisterRawInputDevices`, usage page 1, usages 4 and 5, `RIDEV_INPUTSINK \| RIDEV_DEVNOTIFY`; `GetRawInputBuffer`, `GetRawInputData`, `GetRawInputDeviceInfo`, `GetRawInputDeviceList`) | the reports game controllers send, while the Agent is in the background; a controller arriving and leaving; its vendor and product ids | the documented way to receive a HID controller's reports without being in front, and it opens no handle to the device |
| XInput 1.4 (`XInputGetState`, `XInputGetCapabilities`, `XInputGetBatteryInformation`) | each of its four pads: its state, wired or wireless, a battery in four levels | what an Xbox pad's battery is reported through |
| `GetLastInputInfo` | the time of the last keyboard or mouse input in the user's session | a time and nothing else (D158) |
| `GetForegroundWindow`, `GetWindowThreadProcessId` | whose window is in front | already used for the focus sample (`04_CAPTURE`) |
@@ -51,6 +51,10 @@ Everything is a Windows API in a library Windows ships. **No third-party library
remapper's, exclusive open of it fail. Raw Input needs none.
- **A sixth native library** — parsing bytes a device controls in C++, inside an Agent that may run as administrator.
The reader is C#, and what parses a report is `FrameLedger.Domain.Input`, with no pointer in it.
- **Windows' own HID parser** (`hid.dll`'s `HidP_*`), to read *any* controller generically. It would have let a
controller of a maker this build does not know count as *in use* — and nothing here could be tried on one. A
controller whose layout this build does not know is listed, with its connections and drops, and is never *in
use*: a guess would be a made-up number (§The reader).
## What is never read
@@ -100,6 +104,49 @@ arrives padded to 78 bytes with the id the USB report has: the connection, not t
The layout was written from the open descriptions of the protocol. No code was taken from the Linux kernel's driver,
which is under a licence this project cannot take code from.
## The reader
`Application.Input.InputReader` over `Infrastructure.Input.Win32InputBackend`, on the thread of
`Infrastructure.Input.InputDeviceHub` — named `fl-input`, and **there only while a session has a view of the hub**:
with no session there is no thread, no window and no registration.
**A slice, about ten times a second.** The reader takes what Windows has: the controllers that came and went, the
reports that arrived (in bulk — `GetRawInputBuffer` — not one message at a time: a DualSense sends some hundreds a
second, and the Agent's whole budget is 2.5 % of one core, NFR-2), the state of XInput's connected pads, the time of
the last keyboard or mouse input, and the process whose window is in front. From that it makes one `InputSlice`,
the same for every session that is running; each session's view counts it when a window of *its* game was in front
(`Application.Input.InputTickAccumulator`), and the telemetry poller takes the sum once a second.
**The window.** Raw input is delivered to a window. The reader's is a child of `HWND_MESSAGE`: never shown, in no
task bar, receiving no broadcast, answered by Windows' default procedure. It is registered for HID usage page 1,
usages 4 (joystick) and 5 (gamepad) — `InputReader.RegisteredUsages` — and for nothing else.
**What a controller is.** Each of XInput's pads that is connected is one; each controller Windows does *not* present
through XInput is one. A device Windows presents through XInput is also seen by raw input and is **not** a second
controller: it gives the pads their name where that cannot be mistaken — every XInput-class device a player could
hold has the same two ids — and is otherwise only the witness of the next paragraph. An empty XInput slot is asked
about once in twenty slices (XInput looks for a device each time) and at once when a controller arrives or leaves;
a connected pad's battery once in fifty.
**Where XInput says nothing.** If XInput returns a pad at rest for ever because the Agent's window is never in front
(§XInput), the device's own reports are the evidence: a slice in which an XInput-class device's reports *changed*
while no pad's packet number moved — in that slice or the one before — is counted (`XInputSilent`). After ten of
them, **and only if XInput has never once been seen to move**, such a slice counts the lowest connected pad as in
use. That is coarser than XInput's dead zones — a stick that drifts counts — and is used only where the better
source is silent; a session's stored counts say which it was.
**Which controllers are read for use.** XInput's pads, and a DualSense by its own reports. Any other controller —
a DualShock 4, a Switch Pro controller — is listed with its connections and drops and is never *in use*.
**Faults.** A slice that throws is counted and skipped; twenty in a row end the run with one line in the Agent's
log, and the sessions go on without readings. When a run ends, one line says what it did: slices, whether Windows
accepted the registration, reports received and not read, XInput's reads and silent slices, whether the time of the
last input could be read, the thread's processor time, faults. Nothing in it names a device.
**Held by a gate.** `tools/input-readonly-check.ps1` (`12_BUILD` step 14g): the reader's calls are a committed list,
none of which sends to a device, injects input or reads a key; no other managed source and no native source names
an input function.
## What the reader says about itself
`Application.Input.InputHealth`, carried by every reading and stored with the session: whether Windows accepted the
@@ -0,0 +1,38 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Input;
/// <summary>
/// The Windows calls the input reader makes, behind one interface (<c>21_INPUT_DEVICES</c> §What is read): raw input
/// for game controllers, XInput, the time of the last keyboard or mouse input, the window in front. Everything here
/// reads; nothing writes to a device, and nothing asks about a keyboard or a mouse beyond that one time
/// (<c>tools/input-readonly-check.ps1</c> holds the calls behind it to a list).
/// </summary>
/// <remarks>Every member is called on the reader's own thread, the one that called <see cref="Open"/>.</remarks>
public interface IInputBackend : IDisposable
{
/// <summary>Makes what the reader needs on the calling thread; returns whether Windows accepted the registration for game controllers' reports.</summary>
bool Open();
/// <summary>Hands over what arrived since the last call: the controllers that came and went, then their reports.</summary>
void Drain(IInputBackendSink sink);
/// <summary>Whether XInput's library is there to ask.</summary>
bool XInputAvailable { get; }
/// <summary>The state of one of XInput's four pads; false when it is not connected.</summary>
bool TryReadPad(int slot, out XInputReading pad);
/// <summary>Whether the pad is wireless, and its battery; false when XInput did not answer.</summary>
bool TryReadPadDetails(int slot, out XInputDetails details);
/// <summary>The time of the last keyboard or mouse input in the user's session, as Windows' tick count; false when Windows did not give it.</summary>
bool TryReadLastInputTick(out uint tick);
/// <summary>The process whose window is in front; 0 when there is none.</summary>
uint ForegroundProcessId();
/// <summary>The processor time the calling thread has used, in milliseconds.</summary>
long ThreadCpuMs();
}
@@ -0,0 +1,17 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Input;
/// <summary>What <see cref="IInputBackend.Drain"/> hands over. A device is named by the handle Windows gave it for as long as it is connected: a key, never stored.</summary>
public interface IInputBackendSink
{
/// <summary>A game controller is there: at the start, or newly connected.</summary>
void Arrived(nint device, RawController controller);
/// <summary>It left.</summary>
void Removed(nint device);
/// <summary>One input report of a controller, its report id first, at the length Windows hands the device's reports over.</summary>
void Report(nint device, ReadOnlySpan<byte> report);
}
@@ -0,0 +1,373 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FrameLedger.Domain.Input;
namespace FrameLedger.Application.Input;
/// <summary>
/// The input reader itself (<c>21_INPUT_DEVICES</c> §The reader): about ten times a second it takes what Windows has
/// to say - the controllers' reports that arrived, XInput's four pads, the time of the last keyboard or mouse input,
/// the window in front - and makes one <see cref="InputSlice"/> of it. It is the same for every session running; whose
/// game a slice counts for is <see cref="InputTickAccumulator"/>'s to decide.
/// </summary>
/// <remarks>
/// <para>
/// <b>What a controller is here.</b> Each of XInput's pads that is connected is one; each controller Windows does not
/// present through XInput is one. A device Windows presents through XInput is ALSO seen by raw input, and is not a
/// second controller: it gives the pads their name, when that cannot be mistaken, and is the witness of the next
/// paragraph.
/// </para>
/// <para>
/// <b>XInput in the background is not documented</b>: Microsoft's page for <c>XInputEnable</c> says that since
/// Windows 10 the system switches a program's controller input by its window's focus, and the Agent has no window in
/// front, ever. So the reader watches for it. A slice in which an XInput-class device's own reports changed while no
/// pad's packet number moved - not in this slice nor the one before - is counted
/// (<see cref="InputHealth.XInputSilent"/>). Once there are <see cref="SilentBeforeFallback"/> of them and XInput has
/// never once been seen to move, XInput is taken to be answering nothing here, and from then on such a slice counts
/// the lowest connected pad as in use: its reports changed, which a pad at rest does not do. That is coarser than
/// XInput's own dead zones - a drifting stick counts - and it is used only where the better source is silent.
/// </para>
/// <para>
/// <b>Which controllers are read for use.</b> XInput's pads, and a DualSense by its own reports
/// (<see cref="DualSenseReport"/>). Any other controller is listed, with its connections and drops, and is never "in
/// use": its report layout is not known to this build, and a guess would be a made-up number.
/// </para>
/// </remarks>
public sealed class InputReader : IInputBackendSink
{
/// <summary>XInput's four pads.</summary>
public const int Slots = 4;
/// <summary>A pad that is not connected is asked about once in this many slices - XInput looks for a device each time it is asked about an empty one - and at once when a controller arrives or leaves.</summary>
public const int ProbeEverySlices = 20;
/// <summary>A connected pad's battery is asked for once in this many slices.</summary>
public const int DetailsEverySlices = 50;
/// <summary>How many silent slices, with XInput never seen to move, before a device's own reports stand in for it.</summary>
public const int SilentBeforeFallback = 10;
/// <summary>The number the first controller that is not one of XInput's gets; the pads are 1 to 4.</summary>
private const int _firstRawId = 16;
private readonly IInputBackend _backend;
private readonly Dictionary<nint, Raw> _raw = [];
private readonly Dictionary<(RawController Controller, int Instance), int> _rawIds = [];
private readonly Pad[] _pads = [new(0), new(1), new(2), new(3)];
private bool _registered;
private bool _lastInputAvailable;
private uint? _lastInputTick;
private bool _probeNow = true;
private bool _renamePads = true;
private bool _movedLastSlice;
private bool _xinputEverMoved;
private long _slices;
private long _rawReports;
private long _rawReportsUnread;
private long _xinputReads;
private long _xinputSilent;
private int _faults;
public InputReader(IInputBackend backend) => _backend = backend ?? throw new ArgumentNullException(nameof(backend));
/// <summary>
/// The only device classes the reader registers raw input for: HID usage page 1 (generic desktop), usages 4
/// (joystick) and 5 (gamepad). Never 2 (mouse) or 6 (keyboard): what is known of those is one time, from
/// <see cref="IInputBackend.TryReadLastInputTick"/> (owner decision D158).
/// </summary>
public static IReadOnlyList<(ushort UsagePage, ushort Usage)> RegisteredUsages { get; } = [(1, 4), (1, 5)];
/// <summary>Opens the backend on the calling thread, which is the one every <see cref="Slice"/> must then be called on.</summary>
public void Open() => _registered = _backend.Open();
/// <summary>A slice that threw is counted and skipped.</summary>
public void Fault() => _faults++;
/// <summary>What Windows has to say since the slice before, <paramref name="elapsedMs"/> ago.</summary>
public InputSlice Slice(int elapsedMs)
{
_slices++;
foreach (Raw raw in _raw.Values)
{
raw.Active = false;
raw.Changed = false;
}
_backend.Drain(this);
bool moved = ReadPads();
WatchForSilence(moved);
if (_renamePads)
{
NamePads();
}
bool keyboardMouse = false;
if (_backend.TryReadLastInputTick(out uint tick))
{
_lastInputAvailable = true;
keyboardMouse = _lastInputTick is { } before && tick != before;
_lastInputTick = tick;
}
var devices = new List<InputSliceDevice>(Slots + _raw.Count);
foreach (Pad pad in _pads)
{
if (pad.Connected)
{
devices.Add(new InputSliceDevice(pad.Device, pad.Active, pad.Details is { } d ? XInputPad.Battery(d.BatteryType, d.BatteryLevel) : null));
}
}
foreach (Raw raw in _raw.Values.Where(static r => !r.Controller.XInputClass).OrderBy(static r => r.Device.Id))
{
devices.Add(new InputSliceDevice(raw.Device, raw.Active, raw.Battery));
}
return new InputSlice
{
ElapsedMs = Math.Max(0, elapsedMs),
ForegroundProcessId = _backend.ForegroundProcessId(),
KeyboardMouseActive = keyboardMouse,
VirtualPad = _raw.Values.Any(static r => r.Controller is { XInputClass: true, IsVirtual: true }),
Devices = devices,
Health = new InputHealth
{
RawInputRegistered = _registered,
RawReports = _rawReports,
RawReportsUnread = _rawReportsUnread,
XInputAvailable = _backend.XInputAvailable,
XInputReads = _xinputReads,
XInputSilent = _xinputSilent,
LastInputAvailable = _lastInputAvailable,
Slices = _slices,
ThreadCpuMs = _backend.ThreadCpuMs(),
Faults = _faults,
},
};
}
void IInputBackendSink.Arrived(nint device, RawController controller)
{
if (_raw.TryGetValue(device, out Raw? known) && known.Controller == controller)
{
// Windows names the controllers that are already there when the registration is made, and the reader has
// asked for the list as well: the same device twice is one device.
return;
}
int id = 0;
if (!controller.XInputClass)
{
int instance = _raw.Values.Count(r => r.Controller == controller);
if (!_rawIds.TryGetValue((controller, instance), out id))
{
id = _firstRawId + _rawIds.Count;
_rawIds[(controller, instance)] = id;
}
}
_raw[device] = new Raw(controller, new InputDevice
{
Id = id,
Family = ControllerCatalog.FamilyOf(controller.VendorId, xinput: false),
VendorId = controller.VendorId,
ProductId = controller.ProductId,
Connection = controller.Connection,
});
DevicesChanged(controller);
}
void IInputBackendSink.Removed(nint device)
{
if (_raw.Remove(device, out Raw? gone))
{
DevicesChanged(gone.Controller);
}
}
void IInputBackendSink.Report(nint device, ReadOnlySpan<byte> report)
{
_rawReports++;
if (!_raw.TryGetValue(device, out Raw? raw))
{
_rawReportsUnread++;
return;
}
if (raw.Controller.XInputClass)
{
// The witness only: did the device say something new. What it said is XInput's to tell.
raw.Changed |= raw.Last is not null && !report.SequenceEqual(raw.Last);
if (raw.Last is null || raw.Last.Length != report.Length)
{
raw.Last = report.ToArray();
}
else
{
report.CopyTo(raw.Last);
}
}
else if (raw.Controller.IsDualSense)
{
if (DualSenseReport.TryRead(report, raw.Controller.Connection == ControllerConnection.Bluetooth, out bool active, out BatteryReading? battery))
{
raw.Active |= active;
raw.Battery = battery ?? raw.Battery;
}
else
{
_rawReportsUnread++;
}
}
}
private void DevicesChanged(RawController controller)
{
if (controller.XInputClass)
{
_probeNow = true;
_renamePads = true;
}
}
/// <summary>Asks XInput about its pads; returns whether any connected pad's packet number moved since the slice before.</summary>
private bool ReadPads()
{
bool moved = false;
bool probe = _probeNow || _slices % ProbeEverySlices == 1;
_probeNow = false;
foreach (Pad pad in _pads)
{
pad.Active = false;
if (!_backend.XInputAvailable || (!pad.Connected && !probe))
{
continue;
}
if (!_backend.TryReadPad(pad.Slot, out XInputReading state))
{
if (pad.Connected)
{
pad.Connected = false;
pad.Details = null;
_renamePads = true;
}
continue;
}
_xinputReads++;
if (!pad.Connected)
{
pad.Connected = true;
pad.Details = null;
_renamePads = true;
}
else if (state.Packet != pad.Packet)
{
moved = true;
}
pad.Packet = state.Packet;
pad.Active = XInputPad.IsActive(state.Buttons, state.LeftTrigger, state.RightTrigger, state.ThumbLx, state.ThumbLy, state.ThumbRx, state.ThumbRy);
if (pad.Details is null || _slices - pad.DetailsAt >= DetailsEverySlices)
{
pad.DetailsAt = _slices;
if (_backend.TryReadPadDetails(pad.Slot, out XInputDetails details))
{
_renamePads |= pad.Details?.Wireless != details.Wireless;
pad.Details = details;
}
}
}
return moved;
}
private void WatchForSilence(bool moved)
{
_xinputEverMoved |= moved;
bool deviceSpoke = _raw.Values.Any(static r => r.Controller.XInputClass && r.Changed);
if (deviceSpoke && !moved && !_movedLastSlice && !_pads.Any(static p => p is { Connected: true, Active: true }))
{
_xinputSilent++;
if (!_xinputEverMoved && _xinputSilent >= SilentBeforeFallback && _pads.FirstOrDefault(static p => p.Connected) is { } lowest)
{
lowest.Active = true;
}
}
_movedLastSlice = moved;
}
/// <summary>
/// What each connected pad is. XInput does not say which device a pad is, so a pad is named only when it cannot be
/// another: every XInput-class device a player could hold has the same two ids, or the only ones there are
/// Steam's. Otherwise it is "one of XInput's pads" - the Xbox family, no ids, no model.
/// </summary>
private void NamePads()
{
_renamePads = false;
RawController[] presented = [.. _raw.Values.Where(static r => r.Controller.XInputClass).Select(static r => r.Controller)];
RawController[] held = [.. presented.Where(static c => !c.IsVirtual)];
RawController? name = held.Length > 0
? held.All(c => c.VendorId == held[0].VendorId && c.ProductId == held[0].ProductId) ? held[0] : null
: presented.Length > 0 ? presented[0] : null;
bool bluetooth = name is not null && held.Length > 0 && held.All(static c => c.Connection == ControllerConnection.Bluetooth);
foreach (Pad pad in _pads)
{
pad.Device = new InputDevice
{
Id = pad.Slot + 1,
XInputSlot = pad.Slot,
Family = ControllerCatalog.FamilyOf(name?.VendorId ?? 0, xinput: true),
VendorId = name?.VendorId ?? 0,
ProductId = name?.ProductId ?? 0,
IsVirtual = name?.IsVirtual ?? false,
Connection = bluetooth
? ControllerConnection.Bluetooth
: pad.Details switch
{
{ Wireless: true } => ControllerConnection.Wireless,
{ } => ControllerConnection.Usb,
_ => ControllerConnection.Unknown,
},
};
}
}
/// <summary>One of XInput's pads.</summary>
private sealed class Pad(int slot)
{
public int Slot { get; } = slot;
public bool Connected { get; set; }
public uint Packet { get; set; }
public bool Active { get; set; }
public XInputDetails? Details { get; set; }
public long DetailsAt { get; set; }
public InputDevice Device { get; set; } = new() { Id = slot + 1, XInputSlot = slot, Family = ControllerFamily.Xbox };
}
/// <summary>A controller raw input named.</summary>
private sealed class Raw(RawController controller, InputDevice device)
{
public RawController Controller { get; } = controller;
public InputDevice Device { get; } = device;
public bool Active { get; set; }
public bool Changed { get; set; }
public BatteryReading? Battery { get; set; }
public byte[]? Last { get; set; }
}
}
@@ -0,0 +1,24 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.InteropServices;
using FrameLedger.Domain.Input;
namespace FrameLedger.Application.Input;
/// <summary>
/// A game controller as Windows' raw input describes it, reduced to what the reader keeps: its two USB ids, whether
/// Windows presents it through XInput, and how it is connected. The name these were read from is not here - it can
/// carry an address - and nothing else of the device is asked for.
/// </summary>
/// <param name="VendorId">The USB vendor id.</param>
/// <param name="ProductId">The USB product id.</param>
/// <param name="XInputClass">Whether Windows presents the device through XInput (<see cref="RawDeviceName.IsXInputClass"/>).</param>
/// <param name="Connection">How it is connected (<see cref="RawDeviceName.ConnectionOf"/>).</param>
[StructLayout(LayoutKind.Auto)]
public readonly record struct RawController(int VendorId, int ProductId, bool XInputClass, ControllerConnection Connection)
{
public bool IsVirtual => ControllerCatalog.IsVirtual(VendorId, ProductId);
public bool IsDualSense => !XInputClass && ControllerCatalog.IsDualSense(VendorId, ProductId);
}
@@ -0,0 +1,13 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.InteropServices;
namespace FrameLedger.Application.Input;
/// <summary>What XInput says of one of its pads beside its state: whether it is wireless, and its battery in XInput's own words.</summary>
/// <param name="Wireless"><c>XINPUT_CAPS_WIRELESS</c>.</param>
/// <param name="BatteryType"><c>XINPUT_BATTERY_INFORMATION.BatteryType</c>; 0 (disconnected) when XInput did not answer.</param>
/// <param name="BatteryLevel"><c>XINPUT_BATTERY_INFORMATION.BatteryLevel</c>.</param>
[StructLayout(LayoutKind.Auto)]
public readonly record struct XInputDetails(bool Wireless, int BatteryType, int BatteryLevel);
@@ -0,0 +1,22 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.InteropServices;
namespace FrameLedger.Application.Input;
/// <summary>
/// One of XInput's pads at one read: <c>XINPUT_STATE</c> as it came. The reader asks one thing of it - is this a pad
/// in use (<c>Domain.Input.XInputPad.IsActive</c>) - and whether its packet number moved; neither it nor anything
/// derived from a single button or axis is kept.
/// </summary>
/// <param name="Packet"><c>dwPacketNumber</c>: it moves whenever anything on the pad changed.</param>
/// <param name="Buttons"><c>wButtons</c>.</param>
/// <param name="LeftTrigger"><c>bLeftTrigger</c>, 0-255.</param>
/// <param name="RightTrigger"><c>bRightTrigger</c>, 0-255.</param>
/// <param name="ThumbLx"><c>sThumbLX</c>.</param>
/// <param name="ThumbLy"><c>sThumbLY</c>.</param>
/// <param name="ThumbRx"><c>sThumbRX</c>.</param>
/// <param name="ThumbRy"><c>sThumbRY</c>.</param>
[StructLayout(LayoutKind.Auto)]
public readonly record struct XInputReading(uint Packet, int Buttons, int LeftTrigger, int RightTrigger, int ThumbLx, int ThumbLy, int ThumbRx, int ThumbRy);
@@ -0,0 +1,49 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>
/// The two things FrameLedger takes from the name Windows gives a controller's device interface, after which the name
/// is dropped (<c>21_INPUT_DEVICES</c> §What is never read): whether Windows presents the device through XInput, and
/// how it is connected.
/// </summary>
/// <remarks>
/// <para>
/// The name is a path such as <c>\\?\HID#VID_045E&amp;PID_0B12&amp;IG_00#…</c>. On Bluetooth it carries the service's
/// identifier - and, further along, an instance id that on some stacks is derived from the device's address. That is
/// why the name is never kept, logged or stored: this type returns two facts and holds no string.
/// </para>
/// <para>
/// <b><c>IG_</c></b> is Microsoft's documented mark of a device XInput presents ("XInput and DirectInput": a device id
/// that contains <c>IG_</c> is an XInput device). <b>The connection</b> is Bluetooth when the name carries the
/// identifier of the Bluetooth HID service, classic (<c>00001124-…</c>) or low energy (<c>00001812-…</c>), and USB
/// when it carries a USB vendor id written <c>VID_</c>; anything else is not known.
/// </para>
/// </remarks>
public static class RawDeviceName
{
private const string _xinputMark = "IG_";
private const string _bluetoothClassicService = "{00001124-0000-1000-8000-00805f9b34fb}";
private const string _bluetoothLowEnergyService = "{00001812-0000-1000-8000-00805f9b34fb}";
private const string _usbVendor = "VID_";
/// <summary>Whether Windows presents the device through XInput.</summary>
public static bool IsXInputClass(string? name) => name is not null && name.Contains(_xinputMark, StringComparison.OrdinalIgnoreCase);
/// <summary>How the device is connected, as far as its name says.</summary>
public static ControllerConnection ConnectionOf(string? name)
{
if (string.IsNullOrEmpty(name))
{
return ControllerConnection.Unknown;
}
if (name.Contains(_bluetoothClassicService, StringComparison.OrdinalIgnoreCase) || name.Contains(_bluetoothLowEnergyService, StringComparison.OrdinalIgnoreCase))
{
return ControllerConnection.Bluetooth;
}
return name.Contains(_usbVendor, StringComparison.OrdinalIgnoreCase) ? ControllerConnection.Usb : ControllerConnection.Unknown;
}
}
@@ -0,0 +1,253 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;
using System.Globalization;
using FrameLedger.Application.Input;
using FrameLedger.Application.Telemetry;
namespace FrameLedger.Infrastructure.Input;
/// <summary>
/// The Agent's one input reader, on a thread of its own, running only while a session has a view of it (owner
/// decisions D155-D163, <c>21_INPUT_DEVICES</c> §The reader). With no session it has no thread, no window and no
/// registration: FrameLedger reads nothing about a controller, the keyboard or the mouse.
/// </summary>
/// <remarks>
/// <para>
/// <b>One reader, several sessions.</b> Sessions run side by side (the watcher keeps a table of them), and a
/// controller's reports arrive once. So the thread makes one <see cref="InputSlice"/> about ten times a second and
/// hands it to every view; each view counts it for its own session when a window of that session's game was in front
/// (<see cref="InputTickAccumulator"/>).
/// </para>
/// <para>
/// <b>A pause is a gap here too.</b> While recording is paused (FR-3.9) a slice is not observed by any session.
/// </para>
/// <para>
/// <b>A slice that throws is counted and skipped</b>; <see cref="MaxFaults"/> in a row end the run with one line in
/// the Agent's log, and the sessions go on without readings. Nothing the reader does may end a session.
/// </para>
/// </remarks>
public sealed class InputDeviceHub : IInputDevices, IDisposable
{
/// <summary>Slices that may throw in a row before the run ends.</summary>
public const int MaxFaults = 20;
/// <summary>How long a slice is.</summary>
public static readonly TimeSpan SliceInterval = TimeSpan.FromMilliseconds(100);
private readonly Lock _gate = new();
private readonly Func<IInputBackend> _backendFactory;
private readonly Func<bool> _paused;
private readonly TimeSpan _interval;
private readonly Action<string> _note;
private readonly ManualResetEventSlim _wake = new(initialState: false);
private readonly List<View> _views = [];
private Thread? _thread;
private bool _disposed;
/// <summary>A hub that reads nothing until a view of it is opened.</summary>
/// <param name="backendFactory">Makes the Windows side a run uses; called on the hub's thread, once per run.</param>
/// <param name="paused">Whether recording is paused now; null is never.</param>
/// <param name="interval">How long a slice is; null is <see cref="SliceInterval"/>.</param>
/// <param name="note">Told, in one line, when a run ends - the Agent's log. No line names a device.</param>
public InputDeviceHub(Func<IInputBackend> backendFactory, Func<bool>? paused = null, TimeSpan? interval = null, Action<string>? note = null)
{
ArgumentNullException.ThrowIfNull(backendFactory);
_backendFactory = backendFactory;
_paused = paused ?? (static () => false);
_interval = interval ?? SliceInterval;
ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(_interval, TimeSpan.Zero, nameof(interval));
_note = note ?? (static _ => { });
}
/// <summary>Whether a run is in progress.</summary>
public bool IsRunning
{
get
{
lock (_gate)
{
return _thread is not null;
}
}
}
public IInputActivitySource Open()
{
var view = new View(this);
lock (_gate)
{
ObjectDisposedException.ThrowIf(_disposed, this);
_views.Add(view);
if (_thread is null)
{
_thread = new Thread(Run) { IsBackground = true, Name = "fl-input" };
_thread.Start();
}
}
return view;
}
public void Dispose()
{
Thread? thread;
lock (_gate)
{
if (_disposed)
{
return;
}
_disposed = true;
thread = _thread;
}
_wake.Set();
if (thread is not null && thread != Thread.CurrentThread)
{
thread.Join(TimeSpan.FromSeconds(5));
}
_wake.Dispose();
}
private void Close(View view)
{
lock (_gate)
{
_views.Remove(view);
}
}
private void Run()
{
IInputBackend? backend = null;
InputHealth last = new();
try
{
backend = _backendFactory();
var reader = new InputReader(backend);
reader.Open();
long before = Stopwatch.GetTimestamp();
int faults = 0;
while (Wait())
{
long now = Stopwatch.GetTimestamp();
int elapsed = (int)Math.Min(Stopwatch.GetElapsedTime(before, now).TotalMilliseconds, int.MaxValue);
before = now;
try
{
InputSlice slice = reader.Slice(elapsed);
last = slice.Health;
faults = 0;
Hand(slice);
}
catch (Exception e) when (e is not OperationCanceledException)
{
reader.Fault();
if (++faults >= MaxFaults)
{
_note($"input: the reader's slice threw {MaxFaults} times running and the run ends ({e.GetType().Name}: {e.Message})");
break;
}
}
}
}
catch (Exception e) when (e is not OperationCanceledException)
{
_note($"input: the reader did not start ({e.GetType().Name}: {e.Message})");
}
finally
{
lock (_gate)
{
if (ReferenceEquals(_thread, Thread.CurrentThread))
{
_thread = null;
}
}
backend?.Dispose();
_note(Summary(last));
}
}
/// <summary>What a run did, as the Agent's log keeps it: counts and yes-or-no answers, nothing of any device.</summary>
private static string Summary(InputHealth h) => string.Create(CultureInfo.InvariantCulture,
$"input: run ended - slices {h.Slices}, raw input {(h.RawInputRegistered ? "registered" : "NOT registered")}, reports {h.RawReports} ({h.RawReportsUnread} not read), "
+ $"xinput {(h.XInputAvailable ? "there" : "absent")} with {h.XInputReads} reads and {h.XInputSilent} silent slices, last input {(h.LastInputAvailable ? "read" : "NOT read")}, "
+ $"thread cpu {h.ThreadCpuMs} ms, faults {h.Faults}");
/// <summary>Waits a slice; false when the run is over - the hub is disposed, or no view is open.</summary>
private bool Wait()
{
try
{
_wake.Wait(_interval);
}
catch (ObjectDisposedException)
{
// Dispose gave up waiting for this thread and released the event.
return false;
}
lock (_gate)
{
if (!_disposed && _views.Count > 0)
{
return true;
}
// Decided under the lock and the slot cleared in the same step, so an Open that arrives a moment later
// starts a run of its own rather than joining one that is closing.
if (ReferenceEquals(_thread, Thread.CurrentThread))
{
_thread = null;
}
return false;
}
}
private void Hand(InputSlice slice)
{
View[] views;
lock (_gate)
{
views = [.. _views];
}
bool paused = _paused();
foreach (View view in views)
{
view.Add(slice, paused);
}
}
/// <summary>One session's view.</summary>
private sealed class View(InputDeviceHub hub) : IInputActivitySource
{
private readonly InputTickAccumulator _sum = new();
private volatile int[] _pids = [];
public void Follow(GameProcess target)
{
ArgumentNullException.ThrowIfNull(target);
_pids = target.Pid is { } pinned ? [pinned] : [.. target.Processes.Select(static p => p.Pid)];
}
public bool TryRead([NotNullWhen(true)] out InputReading? reading)
{
reading = _sum.Take();
return reading is not null;
}
public void Add(InputSlice slice, bool paused) =>
_sum.Add(slice, inFront: slice.ForegroundProcessId != 0 && Array.IndexOf(_pids, (int)slice.ForegroundProcessId) >= 0, paused);
public void Dispose() => hub.Close(this);
}
}
@@ -0,0 +1,98 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Buffers.Binary;
using FrameLedger.Application.Input;
namespace FrameLedger.Infrastructure.Input;
/// <summary>
/// The bytes <c>GetRawInputBuffer</c> and <c>GetRawInputData</c> fill, walked without a pointer: a run of
/// <c>RAWINPUT</c> blocks, each a header and - for a HID device - a count of reports of one size
/// (<c>21_INPUT_DEVICES</c> §The reader).
/// </summary>
/// <remarks>
/// <para>
/// Layout on 64-bit Windows, which is all this project builds for: <c>RAWINPUTHEADER</c> is 24 bytes - <c>u32 type</c>,
/// <c>u32 size</c> of the whole block, the device's handle, a parameter - and a <c>RAWHID</c> follows it: <c>u32</c>
/// the size of one report, <c>u32</c> how many, then the reports. The next block starts at the next multiple of eight
/// (<c>NEXTRAWINPUTBLOCK</c>).
/// </para>
/// <para>
/// <b>It trusts no length it reads.</b> A block that claims more than the buffer holds, or less than its own header,
/// ends the walk: what was handed over before it stands, and nothing is read past the buffer. The bytes come from a
/// device by way of Windows, into an Agent that may run as administrator.
/// </para>
/// </remarks>
public static class RawInputBuffer
{
/// <summary><c>sizeof(RAWINPUTHEADER)</c> on 64-bit Windows.</summary>
public const int HeaderBytes = 24;
/// <summary><c>RIM_TYPEHID</c>: the block is a HID device's, the only kind the reader registers for.</summary>
public const uint TypeHid = 2;
private const int _hidHeaderBytes = 8;
/// <summary>Hands each report of each HID block to <paramref name="sink"/>; returns how many blocks were walked.</summary>
/// <param name="buffer">The bytes Windows filled.</param>
/// <param name="blocks">How many blocks Windows said it wrote.</param>
/// <param name="sink">Told each report with its device's handle.</param>
public static int Walk(ReadOnlySpan<byte> buffer, int blocks, IInputBackendSink sink)
{
ArgumentNullException.ThrowIfNull(sink);
int at = 0;
int walked = 0;
for (; walked < blocks; walked++)
{
if (buffer.Length - at < HeaderBytes)
{
break;
}
uint type = BinaryPrimitives.ReadUInt32LittleEndian(buffer[at..]);
uint size = BinaryPrimitives.ReadUInt32LittleEndian(buffer[(at + 4)..]);
if (size < HeaderBytes || size > buffer.Length - at)
{
break;
}
if (type == TypeHid)
{
Reports(buffer.Slice(at, (int)size), sink);
}
// Each block starts on a multiple of eight. The last one may end the buffer without the padding.
at += (int)((size + 7) & ~7u);
if (at > buffer.Length)
{
walked++;
break;
}
}
return walked;
}
private static void Reports(ReadOnlySpan<byte> block, IInputBackendSink sink)
{
if (block.Length < HeaderBytes + _hidHeaderBytes)
{
return;
}
nint device = (nint)BinaryPrimitives.ReadInt64LittleEndian(block[8..]);
uint reportBytes = BinaryPrimitives.ReadUInt32LittleEndian(block[HeaderBytes..]);
uint count = BinaryPrimitives.ReadUInt32LittleEndian(block[(HeaderBytes + 4)..]);
ReadOnlySpan<byte> reports = block[(HeaderBytes + _hidHeaderBytes)..];
if (reportBytes == 0 || count == 0 || (ulong)reportBytes * count > (ulong)reports.Length)
{
return;
}
for (int i = 0; i < count; i++)
{
sink.Report(device, reports.Slice(i * (int)reportBytes, (int)reportBytes));
}
}
}
@@ -0,0 +1,259 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.InteropServices;
namespace FrameLedger.Infrastructure.Input;
/// <summary>
/// Every Windows function the input reader calls, declared in one place so that the list can be held
/// (<c>tools/input-readonly-check.ps1</c>, <c>21_INPUT_DEVICES</c> §What is read): raw input for game controllers,
/// three of XInput's getters, the time of the last input, and the message-only window raw input is delivered to.
/// </summary>
/// <remarks>
/// <b>What is not here is not called.</b> No function that sends anything to a device (<c>XInputSetState</c>, a HID
/// output or feature report), none that reads a key or a button of the keyboard or mouse, no hook. The structures are
/// declared by hand, blittable, with the sizes the tests assert - the reader passes them to Windows by pointer.
/// </remarks>
internal static unsafe class Win32Input
{
public const uint WmInputDeviceChange = 0x00FE;
public const uint WmInput = 0x00FF;
/// <summary><c>GIDC_ARRIVAL</c> / <c>GIDC_REMOVAL</c>: <c>WM_INPUT_DEVICE_CHANGE</c>'s wParam.</summary>
public const nuint DeviceArrival = 1;
public const nuint DeviceRemoval = 2;
/// <summary><c>RIDEV_INPUTSINK</c>: reports are delivered while the caller is not in front.</summary>
public const uint RidevInputSink = 0x00000100;
/// <summary><c>RIDEV_DEVNOTIFY</c>: a device arriving or leaving is told.</summary>
public const uint RidevDevNotify = 0x00002000;
/// <summary><c>RIDEV_REMOVE</c>: ends a registration.</summary>
public const uint RidevRemove = 0x00000001;
public const uint RidiDeviceName = 0x20000007;
public const uint RidiDeviceInfo = 0x2000000B;
/// <summary><c>RID_INPUT</c>: <c>GetRawInputData</c> returns the whole block.</summary>
public const uint RidInput = 0x10000003;
public const uint PmRemove = 0x0001;
/// <summary><c>XINPUT_CAPS_WIRELESS</c>.</summary>
public const ushort XInputCapsWireless = 0x0002;
/// <summary><c>XINPUT_FLAG_GAMEPAD</c>.</summary>
public const uint XInputFlagGamepad = 0x00000001;
/// <summary><c>BATTERY_DEVTYPE_GAMEPAD</c>.</summary>
public const byte BatteryDevTypeGamepad = 0x00;
/// <summary><c>HWND_MESSAGE</c>: the parent of a window that is never shown and receives no broadcast.</summary>
public static readonly nint HwndMessage = -3;
private const string _user32 = "user32.dll";
private const string _kernel32 = "kernel32.dll";
private const string _xinput = "xinput1_4.dll";
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern ushort RegisterClassExW(WndClassEx* windowClass);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true)]
public static extern int UnregisterClassW(char* className, nint instance);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern nint CreateWindowExW(uint exStyle, char* className, char* windowName, uint style, int x, int y, int width, int height, nint parent, nint menu, nint instance, void* param);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true)]
public static extern int DestroyWindow(nint window);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true)]
public static extern nint DefWindowProcW(nint window, uint message, nuint wParam, nint lParam);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true)]
public static extern int PeekMessageW(Message* message, nint window, uint filterMin, uint filterMax, uint remove);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true)]
public static extern nint DispatchMessageW(Message* message);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern int RegisterRawInputDevices(RawInputDevice* devices, uint count, uint size);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern uint GetRawInputBuffer(void* data, uint* size, uint headerSize);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern uint GetRawInputData(nint rawInput, uint command, void* data, uint* size, uint headerSize);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern uint GetRawInputDeviceInfoW(nint device, uint command, void* data, uint* size);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern uint GetRawInputDeviceList(RawInputDeviceListEntry* list, uint* count, uint size);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true)]
public static extern int GetLastInputInfo(LastInputInfo* info);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_kernel32, ExactSpelling = true)]
public static extern nint GetModuleHandleW(char* name);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_kernel32, ExactSpelling = true)]
public static extern nint GetCurrentThread();
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_kernel32, ExactSpelling = true)]
public static extern int GetThreadTimes(nint thread, long* creation, long* exit, long* kernel, long* user);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_xinput, ExactSpelling = true)]
public static extern uint XInputGetState(uint userIndex, XInputState* state);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_xinput, ExactSpelling = true)]
public static extern uint XInputGetCapabilities(uint userIndex, uint flags, XInputCapabilities* capabilities);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_xinput, ExactSpelling = true)]
public static extern uint XInputGetBatteryInformation(uint userIndex, byte deviceType, XInputBatteryInformation* battery);
/// <summary><c>WNDCLASSEXW</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct WndClassEx
{
public uint Size;
public uint Style;
public delegate* unmanaged[Stdcall]<nint, uint, nuint, nint, nint> WndProc;
public int ClassExtra;
public int WindowExtra;
public nint Instance;
public nint Icon;
public nint Cursor;
public nint Background;
public char* MenuName;
public char* ClassName;
public nint SmallIcon;
}
/// <summary><c>MSG</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct Message
{
public nint Window;
public uint Id;
public nuint WParam;
public nint LParam;
public uint Time;
public int X;
public int Y;
}
/// <summary><c>RAWINPUTDEVICE</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct RawInputDevice
{
public ushort UsagePage;
public ushort Usage;
public uint Flags;
public nint Target;
}
/// <summary><c>RAWINPUTDEVICELIST</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct RawInputDeviceListEntry
{
public nint Device;
public uint Type;
}
/// <summary><c>RID_DEVICE_INFO</c>, with the HID member of its union - the only one the reader looks at.</summary>
[StructLayout(LayoutKind.Explicit, Size = 32)]
public struct RidDeviceInfo
{
[FieldOffset(0)]
public uint Size;
[FieldOffset(4)]
public uint Type;
[FieldOffset(8)]
public uint VendorId;
[FieldOffset(12)]
public uint ProductId;
[FieldOffset(16)]
public uint VersionNumber;
[FieldOffset(20)]
public ushort UsagePage;
[FieldOffset(22)]
public ushort Usage;
}
/// <summary><c>XINPUT_GAMEPAD</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct XInputGamepad
{
public ushort Buttons;
public byte LeftTrigger;
public byte RightTrigger;
public short ThumbLx;
public short ThumbLy;
public short ThumbRx;
public short ThumbRy;
}
/// <summary><c>XINPUT_STATE</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct XInputState
{
public uint PacketNumber;
public XInputGamepad Gamepad;
}
/// <summary><c>XINPUT_CAPABILITIES</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct XInputCapabilities
{
public byte Type;
public byte SubType;
public ushort Flags;
public XInputGamepad Gamepad;
public ushort LeftMotor;
public ushort RightMotor;
}
/// <summary><c>XINPUT_BATTERY_INFORMATION</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct XInputBatteryInformation
{
public byte Type;
public byte Level;
}
/// <summary><c>LASTINPUTINFO</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct LastInputInfo
{
public uint Size;
public uint Time;
}
}
@@ -0,0 +1,383 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
using FrameLedger.Application.Input;
using FrameLedger.Domain.Input;
using FrameLedger.Infrastructure.Io;
using Microsoft.Win32.SafeHandles;
namespace FrameLedger.Infrastructure.Input;
/// <summary>
/// The input reader's Windows side (<c>21_INPUT_DEVICES</c> §The reader): a window that is never shown, registered to
/// receive game controllers' reports while the Agent is in the background; three of XInput's getters; the time of the
/// last keyboard or mouse input; the window in front.
/// </summary>
/// <remarks>
/// <para>
/// <b>It opens no device.</b> Raw input hands the reports over; a handle of FrameLedger's on a controller could make a
/// game's own exclusive open of it fail. <b>It sends nothing to a device</b> and asks none for a feature report (owner
/// decision D159). <b>It registers for game controllers only</b> - <see cref="InputReader.RegisteredUsages"/> - never
/// for a keyboard or a mouse (D158).
/// </para>
/// <para>
/// <b>Reports are read in bulk, once a slice</b> (<c>GetRawInputBuffer</c>), not one message at a time: a DualSense
/// sends some hundreds a second, and the Agent's whole budget is 2.5 % of one core (NFR-2). A report that still comes
/// as a message is read too, so that neither path alone has to be the one that works on a given PC.
/// </para>
/// <para>
/// <b>A device's name is read and dropped.</b> It says whether Windows presents the device through XInput and how it
/// is connected (<see cref="RawDeviceName"/>); it can also carry an address, so it is never kept, logged or returned.
/// </para>
/// <para>
/// <b>No controller was at hand when this was written</b> (owner decision D157). What it does with none connected is
/// under test; what it does with one is owner-only item 48, read from the counts every session stores.
/// </para>
/// </remarks>
public sealed unsafe class Win32InputBackend : IInputBackend
{
/// <summary>The most messages one drain takes off the queue, and the most reads of the buffer: a slice is short.</summary>
private const int _maxMessages = 2048;
private const int _maxBufferReads = 64;
private const int _bufferBytes = 64 * 1024;
private const int _maxNameChars = 1024;
private const uint _success = 0;
private const uint _failed = unchecked((uint)-1);
private const string _className = "FrameLedger.InputReader";
private readonly List<(nint Device, RawController Controller)> _present = [];
private byte[]? _buffer;
private MessageWindow? _window;
private bool _classRegistered;
private bool _registered;
private bool _xinputAvailable = true;
private bool _disposed;
public bool XInputAvailable => _xinputAvailable;
public bool Open()
{
ObjectDisposedException.ThrowIf(_disposed, this);
AssertLayout();
// On the pinned heap and so at an address a multiple of eight, which GetRawInputBuffer requires of its buffer.
_buffer = GC.AllocateUninitializedArray<byte>(_bufferBytes, pinned: true);
nint instance = Win32Input.GetModuleHandleW(null);
nint window;
fixed (char* name = _className)
{
var windowClass = new Win32Input.WndClassEx
{
Size = (uint)sizeof(Win32Input.WndClassEx),
WndProc = &WindowProcedure,
Instance = instance,
ClassName = name,
};
// Zero with the class already there is fine: an earlier reader of this process registered it.
_classRegistered = Win32Input.RegisterClassExW(&windowClass) != 0;
window = Win32Input.CreateWindowExW(0, name, name, 0, 0, 0, 0, 0, Win32Input.HwndMessage, 0, instance, null);
}
if (window == 0)
{
return false;
}
_window = new MessageWindow(window);
_registered = Register(Win32Input.RidevInputSink | Win32Input.RidevDevNotify, window);
if (_registered)
{
ListPresent();
}
return _registered;
}
public void Drain(IInputBackendSink sink)
{
ArgumentNullException.ThrowIfNull(sink);
if (_window is null || _buffer is null)
{
return;
}
// The controllers that were there when the reader opened, once.
foreach ((nint device, RawController controller) in _present)
{
sink.Arrived(device, controller);
}
_present.Clear();
// First who came and went, so that a report is never of a device nobody has named yet.
Win32Input.Message message;
for (int i = 0; i < _maxMessages && Win32Input.PeekMessageW(&message, 0, Win32Input.WmInputDeviceChange, Win32Input.WmInputDeviceChange, Win32Input.PmRemove) != 0; i++)
{
DeviceChanged(message, sink);
}
ReadBuffered(sink);
// Then whatever is left on the queue. A report that came as a message is read as one; anything else is the
// window's to answer, which for this window is the default.
for (int i = 0; i < _maxMessages && Win32Input.PeekMessageW(&message, 0, 0, 0, Win32Input.PmRemove) != 0; i++)
{
if (message.Id == Win32Input.WmInputDeviceChange)
{
DeviceChanged(message, sink);
}
else if (message.Id == Win32Input.WmInput)
{
ReadMessage(message.LParam, sink);
}
Win32Input.DispatchMessageW(&message);
}
}
public bool TryReadPad(int slot, out XInputReading pad)
{
pad = default;
if (!_xinputAvailable)
{
return false;
}
Win32Input.XInputState state;
try
{
if (Win32Input.XInputGetState((uint)slot, &state) != _success)
{
return false;
}
}
catch (Exception e) when (e is DllNotFoundException or EntryPointNotFoundException)
{
_xinputAvailable = false;
return false;
}
Win32Input.XInputGamepad g = state.Gamepad;
pad = new XInputReading(state.PacketNumber, g.Buttons, g.LeftTrigger, g.RightTrigger, g.ThumbLx, g.ThumbLy, g.ThumbRx, g.ThumbRy);
return true;
}
public bool TryReadPadDetails(int slot, out XInputDetails details)
{
details = default;
if (!_xinputAvailable)
{
return false;
}
try
{
Win32Input.XInputCapabilities capabilities;
if (Win32Input.XInputGetCapabilities((uint)slot, Win32Input.XInputFlagGamepad, &capabilities) != _success)
{
return false;
}
// A pad whose battery XInput does not answer about - one on Bluetooth is reported not to - still has its
// wireless flag: type 0 is XInput's own "disconnected", which reads as no battery to show.
Win32Input.XInputBatteryInformation battery = default;
bool answered = Win32Input.XInputGetBatteryInformation((uint)slot, Win32Input.BatteryDevTypeGamepad, &battery) == _success;
details = new XInputDetails((capabilities.Flags & Win32Input.XInputCapsWireless) != 0, answered ? battery.Type : 0, answered ? battery.Level : 0);
return true;
}
catch (Exception e) when (e is DllNotFoundException or EntryPointNotFoundException)
{
_xinputAvailable = false;
return false;
}
}
public bool TryReadLastInputTick(out uint tick)
{
var info = new Win32Input.LastInputInfo { Size = (uint)sizeof(Win32Input.LastInputInfo) };
bool read = Win32Input.GetLastInputInfo(&info) != 0;
tick = read ? info.Time : 0;
return read;
}
public uint ForegroundProcessId() => ForegroundWindowProbe.ForegroundProcessId();
public long ThreadCpuMs()
{
long creation;
long exit;
long kernel;
long user;
return Win32Input.GetThreadTimes(Win32Input.GetCurrentThread(), &creation, &exit, &kernel, &user) != 0
? (kernel + user) / TimeSpan.TicksPerMillisecond
: 0;
}
/// <summary>
/// Ends the registration and destroys the window. Called on the thread that opened it: a window belongs to its
/// thread, and Windows refuses another's attempt to destroy it.
/// </summary>
public void Dispose()
{
if (_disposed)
{
return;
}
_disposed = true;
if (_registered)
{
// Ending a registration names no window (the API refuses one there).
Register(Win32Input.RidevRemove, target: 0);
_registered = false;
}
_window?.Dispose();
_window = null;
if (_classRegistered)
{
fixed (char* name = _className)
{
_ = Win32Input.UnregisterClassW(name, Win32Input.GetModuleHandleW(null));
}
_classRegistered = false;
}
_buffer = null;
}
[UnmanagedCallersOnly(CallConvs = [typeof(CallConvStdcall)])]
private static nint WindowProcedure(nint window, uint message, nuint wParam, nint lParam) => Win32Input.DefWindowProcW(window, message, wParam, lParam);
/// <summary>The structures are passed to Windows by pointer: a size that is not Windows' is a bug to stop on, not to read with.</summary>
private static void AssertLayout()
{
if (sizeof(Win32Input.WndClassEx) != 80 || sizeof(Win32Input.Message) != 48 || sizeof(Win32Input.RawInputDevice) != 16
|| sizeof(Win32Input.RawInputDeviceListEntry) != 16 || sizeof(Win32Input.RidDeviceInfo) != 32 || sizeof(Win32Input.XInputState) != 16
|| sizeof(Win32Input.XInputCapabilities) != 20 || sizeof(Win32Input.XInputBatteryInformation) != 2 || sizeof(Win32Input.LastInputInfo) != 8
|| nint.Size != 8)
{
throw new InvalidOperationException("the input reader's structures are not the size Windows expects of them");
}
}
private static bool Register(uint flags, nint target)
{
IReadOnlyList<(ushort UsagePage, ushort Usage)> usages = InputReader.RegisteredUsages;
Win32Input.RawInputDevice* devices = stackalloc Win32Input.RawInputDevice[usages.Count];
for (int i = 0; i < usages.Count; i++)
{
devices[i] = new Win32Input.RawInputDevice { UsagePage = usages[i].UsagePage, Usage = usages[i].Usage, Flags = flags, Target = target };
}
return Win32Input.RegisterRawInputDevices(devices, (uint)usages.Count, (uint)sizeof(Win32Input.RawInputDevice)) != 0;
}
private void ListPresent()
{
uint count = 0;
uint entry = (uint)sizeof(Win32Input.RawInputDeviceListEntry);
if (Win32Input.GetRawInputDeviceList(null, &count, entry) == _failed || count is 0 or > 4096)
{
return;
}
var list = new Win32Input.RawInputDeviceListEntry[count];
fixed (Win32Input.RawInputDeviceListEntry* p = list)
{
uint written = Win32Input.GetRawInputDeviceList(p, &count, entry);
if (written == _failed)
{
return;
}
for (int i = 0; i < written && i < list.Length; i++)
{
if (list[i].Type == RawInputBuffer.TypeHid && Describe(list[i].Device) is { } controller)
{
_present.Add((list[i].Device, controller));
}
}
}
}
private static void DeviceChanged(Win32Input.Message message, IInputBackendSink sink)
{
if (message.WParam == Win32Input.DeviceArrival)
{
if (Describe(message.LParam) is { } controller)
{
sink.Arrived(message.LParam, controller);
}
}
else if (message.WParam == Win32Input.DeviceRemoval)
{
sink.Removed(message.LParam);
}
}
/// <summary>What a device is, when it is a game controller; null for anything else, and for a device that left before it could be asked.</summary>
private static RawController? Describe(nint device)
{
var info = new Win32Input.RidDeviceInfo { Size = (uint)sizeof(Win32Input.RidDeviceInfo) };
uint size = info.Size;
uint written = Win32Input.GetRawInputDeviceInfoW(device, Win32Input.RidiDeviceInfo, &info, &size);
if (written is 0 or _failed || info.Type != RawInputBuffer.TypeHid
|| !InputReader.RegisteredUsages.Contains((info.UsagePage, info.Usage)))
{
return null;
}
// The name is used for the two facts below and goes no further than this method.
char* name = stackalloc char[_maxNameChars];
uint chars = _maxNameChars;
uint copied = Win32Input.GetRawInputDeviceInfoW(device, Win32Input.RidiDeviceName, name, &chars);
string? path = copied is 0 or _failed || copied > _maxNameChars ? null : new string(name, 0, (int)copied).TrimEnd('\0');
return new RawController((int)(info.VendorId & 0xFFFF), (int)(info.ProductId & 0xFFFF), RawDeviceName.IsXInputClass(path), RawDeviceName.ConnectionOf(path));
}
private void ReadBuffered(IInputBackendSink sink)
{
fixed (byte* buffer = _buffer)
{
for (int i = 0; i < _maxBufferReads; i++)
{
uint size = _bufferBytes;
uint blocks = Win32Input.GetRawInputBuffer(buffer, &size, RawInputBuffer.HeaderBytes);
if (blocks is 0 or _failed)
{
return;
}
RawInputBuffer.Walk(new ReadOnlySpan<byte>(buffer, _bufferBytes), (int)Math.Min(blocks, int.MaxValue), sink);
}
}
}
/// <summary>The message-only window, as a handle that is destroyed once.</summary>
private sealed class MessageWindow : SafeHandleZeroOrMinusOneIsInvalid
{
public MessageWindow(nint window)
: base(ownsHandle: true) => SetHandle(window);
protected override bool ReleaseHandle() => Win32Input.DestroyWindow(handle) != 0;
}
private void ReadMessage(nint rawInput, IInputBackendSink sink)
{
fixed (byte* buffer = _buffer)
{
uint size = _bufferBytes;
uint written = Win32Input.GetRawInputData(rawInput, Win32Input.RidInput, buffer, &size, RawInputBuffer.HeaderBytes);
if (written is not (0 or _failed) && written <= _bufferBytes)
{
RawInputBuffer.Walk(new ReadOnlySpan<byte>(buffer, (int)written), 1, sink);
}
}
}
}
@@ -29,4 +29,9 @@
<Using Include="Xunit" />
</ItemGroup>
<!-- Windows as the input reader asks it, with every answer written by the test (D157): shared with the other suites that drive the reader. -->
<ItemGroup>
<Compile Include="..\Shared\FakeInputBackend.cs" Link="Shared\FakeInputBackend.cs" />
</ItemGroup>
</Project>
@@ -0,0 +1,456 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FluentAssertions;
using FrameLedger.Application.Input;
using FrameLedger.Domain.Input;
using FrameLedger.Testing;
namespace FrameLedger.Application.Tests.Input;
/// <summary>
/// The input reader over a Windows whose every answer the test writes (<c>21_INPUT_DEVICES</c> §The reader): what a
/// controller is, when it is in use, what stands in for XInput where XInput says nothing, and what the reader says of
/// itself. <b>No device is behind any of it</b> - what a real controller answers is owner-only item 48.
/// </summary>
public sealed class InputReaderTests
{
private const nint _deviceA = 0x1001;
private const nint _deviceB = 0x1002;
private static readonly RawController _xboxBluetooth = new(ControllerCatalog.Microsoft, 0x0B13, XInputClass: true, ControllerConnection.Bluetooth);
private static readonly RawController _xboxUsb = new(ControllerCatalog.Microsoft, 0x0B12, XInputClass: true, ControllerConnection.Usb);
private static readonly RawController _steamPad = new(ControllerCatalog.Valve, ControllerCatalog.SteamVirtualGamepad, XInputClass: true, ControllerConnection.Usb);
private static readonly RawController _dualSenseUsb = new(ControllerCatalog.Sony, ControllerCatalog.DualSense, XInputClass: false, ControllerConnection.Usb);
private static readonly RawController _dualSenseBluetooth = _dualSenseUsb with { Connection = ControllerConnection.Bluetooth };
private static readonly RawController _dualShock = new(ControllerCatalog.Sony, 0x09CC, XInputClass: false, ControllerConnection.Usb);
private static readonly XInputReading _atRest = new(Packet: 7, 0, 0, 0, 0, 0, 0, 0);
private static readonly XInputReading _buttonDown = _atRest with { Packet = 8, Buttons = 0x1000 };
private static (InputReader Reader, FakeInputBackend Backend) Make()
{
var backend = new FakeInputBackend();
var reader = new InputReader(backend);
reader.Open();
return (reader, backend);
}
/// <summary>A USB report of a DualSense: at rest, or with a button down; the battery byte as given.</summary>
private static byte[] DualSenseUsb(bool pressed = false, byte status = 0x08)
{
byte[] report = new byte[DualSenseReport.UsbLength];
report[0] = 0x01;
report[1] = report[2] = report[3] = report[4] = 128;
report[8] = pressed ? (byte)0x28 : (byte)0x08;
report[53] = status;
return report;
}
[Fact]
public void WithNothingConnectedASliceHasNoControllerAndSaysWhatAnswered()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.CpuMs = 3;
InputSlice slice = reader.Slice(104);
backend.Opened.Should().BeTrue();
slice.ElapsedMs.Should().Be(104);
slice.ForegroundProcessId.Should().Be(42);
slice.Devices.Should().BeEmpty();
slice.KeyboardMouseActive.Should().BeFalse("the first slice has no time before it to compare with");
slice.VirtualPad.Should().BeFalse();
slice.Health.Should().Be(new InputHealth { RawInputRegistered = true, XInputAvailable = true, LastInputAvailable = true, Slices = 1, ThreadCpuMs = 3 });
}
[Fact]
public void TheOnlyDevicesRawInputIsRegisteredForAreJoysticksAndGamepads() =>
InputReader.RegisteredUsages.Should().Equal([(1, 4), (1, 5)], "usage 2 is a mouse and 6 a keyboard: neither is ever registered for (D158)");
/// <summary>XInput looks for a device each time it is asked about an empty slot, so an empty slot is asked about rarely.</summary>
[Fact]
public void AnEmptySlotIsAskedAboutOnceInTwentySlicesAndAConnectedOneEverySlice()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[1] = _atRest;
for (int i = 0; i < InputReader.ProbeEverySlices; i++)
{
reader.Slice(100);
}
backend.PadAsks.Should().Equal(1, InputReader.ProbeEverySlices, 1, 1);
reader.Slice(100);
backend.PadAsks.Should().Equal(2, InputReader.ProbeEverySlices + 1, 2, 2);
}
[Fact]
public void AnXInputPadIsAControllerOfTheXboxFamilyAndIsInUseWhenItsStateSaysSo()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[2] = _buttonDown;
InputSliceDevice pad = reader.Slice(100).Devices.Should().ContainSingle().Subject;
pad.Device.Should().Be(new InputDevice { Id = 3, Family = ControllerFamily.Xbox, XInputSlot = 2 });
pad.Device.Model.Should().BeNull("XInput does not say which device a pad is, and nothing else named it");
pad.Active.Should().BeTrue();
pad.Battery.Should().BeNull("XInput was not asked, or did not answer");
backend.Pads[2] = _atRest with { ThumbLx = 5000, ThumbLy = 5000 };
reader.Slice(100).Devices[0].Active.Should().BeFalse("a stick inside its dead zone is drift");
backend.Pads.Remove(2);
reader.Slice(100).Devices.Should().BeEmpty("XInput says it is not connected any more");
}
[Fact]
public void APadsBatteryAndWirelessFlagAreAskedForWhenItConnectsAndThenOnceInFiftySlices()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[0] = _atRest;
backend.Details[0] = new XInputDetails(Wireless: true, BatteryType: 3, BatteryLevel: 2);
InputSliceDevice pad = reader.Slice(100).Devices[0];
pad.Battery.Should().Be(new BatteryReading(BatteryState.Discharging, BatteryScale.FourLevels, 2));
pad.Device.Connection.Should().Be(ControllerConnection.Wireless);
backend.DetailAsks.Should().Be(1);
backend.Details[0] = new XInputDetails(Wireless: false, BatteryType: 1, BatteryLevel: 0);
for (int i = 0; i < InputReader.DetailsEverySlices - 1; i++)
{
reader.Slice(100);
}
backend.DetailAsks.Should().Be(1, "not yet");
pad = reader.Slice(100).Devices[0];
backend.DetailAsks.Should().Be(2);
pad.Battery.Should().Be(BatteryReading.Wired);
pad.Device.Connection.Should().Be(ControllerConnection.Usb, "the pad is wired now, and its description follows");
}
[Fact]
public void APadIsNamedWhenTheOnlyXInputClassDeviceThereCanBeIt()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[0] = _atRest;
backend.Details[0] = new XInputDetails(Wireless: true, BatteryType: 0, BatteryLevel: 0);
backend.Arrive(_deviceA, _xboxBluetooth);
InputSlice slice = reader.Slice(100);
InputSliceDevice pad = slice.Devices.Should().ContainSingle("the device raw input named IS the pad, not a second controller").Subject;
pad.Device.Should().Be(new InputDevice
{
Id = 1,
Family = ControllerFamily.Xbox,
VendorId = ControllerCatalog.Microsoft,
ProductId = 0x0B13,
Connection = ControllerConnection.Bluetooth,
XInputSlot = 0,
});
pad.Device.Model.Should().Be("Xbox Wireless Controller");
pad.Battery.Should().BeNull("type 0 is XInput's own word for nothing to show - a pad on Bluetooth is reported not to answer");
slice.VirtualPad.Should().BeFalse();
}
[Fact]
public void TwoDifferentXInputClassDevicesLeaveThePadsUnnamed()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[0] = _atRest;
backend.Pads[1] = _atRest;
backend.Arrive(_deviceA, _xboxBluetooth);
backend.Arrive(_deviceB, _xboxUsb);
IReadOnlyList<InputSliceDevice> pads = reader.Slice(100).Devices;
pads.Should().HaveCount(2);
pads.Should().OnlyContain(static p => p.Device.VendorId == 0 && p.Device.Family == ControllerFamily.Xbox, "which pad is which device cannot be told, and a wrong name is worse than none");
backend.Leave(_deviceB);
reader.Slice(100).Devices.Should().OnlyContain(static p => p.Device.ProductId == 0x0B13, "one device left: both pads can only be it");
}
[Fact]
public void SteamsVirtualGamepadMarksTheSliceAndNamesThePadsOnlyWhenNothingElseCan()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[0] = _atRest;
backend.Arrive(_deviceA, _steamPad);
InputSlice alone = reader.Slice(100);
alone.VirtualPad.Should().BeTrue();
alone.Devices.Should().ContainSingle().Which.Device.Should().BeEquivalentTo(new InputDevice
{
Id = 1,
Family = ControllerFamily.Xbox,
VendorId = ControllerCatalog.Valve,
ProductId = ControllerCatalog.SteamVirtualGamepad,
IsVirtual = true,
XInputSlot = 0,
});
backend.Arrive(_deviceB, _xboxUsb);
InputSlice beside = reader.Slice(100);
beside.VirtualPad.Should().BeTrue();
beside.Devices[0].Device.IsVirtual.Should().BeFalse("with a pad a player holds beside it, the pads take that pad's name");
beside.Devices[0].Device.ProductId.Should().Be(0x0B12);
}
[Fact]
public void ADualSenseIsReadFromItsOwnReports()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Arrive(_deviceA, _dualSenseUsb);
backend.Send(_deviceA, DualSenseUsb());
backend.Send(_deviceA, DualSenseUsb(pressed: true, status: 0x07));
backend.Send(_deviceA, DualSenseUsb(status: 0x06));
InputSlice slice = reader.Slice(100);
InputSliceDevice pad = slice.Devices.Should().ContainSingle().Subject;
pad.Device.Should().Be(new InputDevice { Id = 16, Family = ControllerFamily.PlayStation, VendorId = ControllerCatalog.Sony, ProductId = ControllerCatalog.DualSense, Connection = ControllerConnection.Usb });
pad.Active.Should().BeTrue("one of the slice's reports was a pad in use");
pad.Battery.Should().Be(new BatteryReading(BatteryState.Discharging, BatteryScale.Percent, 60), "the last report's");
slice.Health.RawReports.Should().Be(3);
slice.Health.RawReportsUnread.Should().Be(0);
InputSliceDevice later = reader.Slice(100).Devices[0];
later.Active.Should().BeFalse("no report in this slice said so");
later.Battery.Should().Be(pad.Battery, "the level a pad last reported is still its level");
}
[Fact]
public void ADualSenseOnBluetoothIsReadByItsShortReportUntilSomethingElseSwitchesIt()
{
(InputReader reader, FakeInputBackend backend) = Make();
byte[] shortReport = new byte[DualSenseReport.BluetoothLength];
shortReport[0] = 0x01;
shortReport[1] = shortReport[2] = shortReport[3] = shortReport[4] = 128;
shortReport[5] = 0x08;
shortReport[8] = 200;
backend.Arrive(_deviceA, _dualSenseBluetooth);
backend.Send(_deviceA, shortReport);
InputSliceDevice pad = reader.Slice(100).Devices[0];
pad.Active.Should().BeTrue();
pad.Battery.Should().BeNull("the short report has none, and the reader never asks the pad for the long one (D159)");
pad.Device.Connection.Should().Be(ControllerConnection.Bluetooth);
}
[Fact]
public void AReportTheParserCannotReadAndAReportOfADeviceNobodyNamedAreCountedAsNotRead()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Arrive(_deviceA, _dualSenseUsb);
backend.Send(_deviceA, 0x7F, 1, 2, 3);
backend.Send(_deviceB, DualSenseUsb(pressed: true));
InputSlice slice = reader.Slice(100);
slice.Health.RawReports.Should().Be(2);
slice.Health.RawReportsUnread.Should().Be(2);
slice.Devices.Should().ContainSingle().Which.Active.Should().BeFalse();
}
/// <summary>A controller whose layout this build does not know is listed, with its connections and drops, and is never "in use": a guess would be a made-up number.</summary>
[Fact]
public void AControllerWhoseReportsThisBuildCannotReadIsListedAndNeverInUse()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Arrive(_deviceA, _dualShock);
backend.Send(_deviceA, 1, 255, 255, 255, 255, 255, 255, 255);
InputSlice slice = reader.Slice(100);
InputSliceDevice pad = slice.Devices.Should().ContainSingle().Subject;
pad.Device.Family.Should().Be(ControllerFamily.PlayStation);
pad.Device.Model.Should().Be("DualShock 4");
pad.Active.Should().BeFalse();
pad.Battery.Should().BeNull();
slice.Health.RawReportsUnread.Should().Be(0, "it is not a report the reader set out to read");
}
[Fact]
public void AControllerKeepsItsNumberAcrossAReconnectAndASecondOfTheSameModelHasItsOwn()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Arrive(_deviceA, _dualSenseUsb);
backend.Arrive(_deviceA, _dualSenseUsb);
reader.Slice(100).Devices.Select(static d => d.Device.Id).Should().Equal([16], "Windows naming a device twice is one device");
backend.Leave(_deviceA);
reader.Slice(100).Devices.Should().BeEmpty();
backend.Arrive(_deviceB, _dualSenseUsb);
reader.Slice(100).Devices.Select(static d => d.Device.Id).Should().Equal([16], "the same model on the same connection, back under another handle");
backend.Arrive(_deviceA, _dualSenseUsb);
backend.Arrive(0x1003, _dualSenseBluetooth);
reader.Slice(100).Devices.Select(static d => d.Device.Id).Should().Equal(16, 17, 18);
backend.Leave(0x4242);
reader.Slice(100).Devices.Should().HaveCount(3, "a device nobody named leaving changes nothing");
}
[Fact]
public void TheKeyboardOrMouseWasInUseWhenWindowsTimeOfTheLastInputMoved()
{
(InputReader reader, FakeInputBackend backend) = Make();
reader.Slice(100).KeyboardMouseActive.Should().BeFalse();
reader.Slice(100).KeyboardMouseActive.Should().BeFalse("the time did not move");
backend.LastInputTick = 1090;
reader.Slice(100).KeyboardMouseActive.Should().BeTrue();
reader.Slice(100).KeyboardMouseActive.Should().BeFalse();
backend.LastInputTick = 900;
reader.Slice(100).KeyboardMouseActive.Should().BeTrue("Windows does not promise the time only goes forward; a different one is input all the same");
}
[Fact]
public void WhenWindowsDoesNotGiveTheTimeOfTheLastInputNothingIsSaidOfTheKeyboardAndTheHealthSaysSo()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.LastInputTick = null;
InputSlice slice = reader.Slice(100);
slice.KeyboardMouseActive.Should().BeFalse();
slice.Health.LastInputAvailable.Should().BeFalse();
slice.Health.Sources().Should().Be("rawinput+xinput");
}
[Fact]
public void WithoutXInputsLibraryNoPadIsAskedAbout()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.XInputAvailable = false;
backend.Pads[0] = _buttonDown;
InputSlice slice = reader.Slice(100);
slice.Devices.Should().BeEmpty();
slice.Health.XInputAvailable.Should().BeFalse();
backend.PadAsks.Should().Equal(0, 0, 0, 0);
}
/// <summary>
/// Microsoft's page for XInputEnable says the system switches a program's controller input by its window's focus.
/// Where that leaves the Agent with a pad that reads at rest for ever, the device's own reports stand in.
/// </summary>
[Fact]
public void WhereXInputSaysNothingWhileTheDevicesReportsChangeThePadCountsAsInUseAfterTenSuchSlices()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[1] = _atRest;
backend.Arrive(_deviceA, _xboxUsb);
backend.Send(_deviceA, 0, 1);
reader.Slice(100).Devices[0].Active.Should().BeFalse("the first report has nothing before it to differ from");
for (int i = 1; i < InputReader.SilentBeforeFallback; i++)
{
backend.Send(_deviceA, 0, (byte)(i + 1));
InputSlice early = reader.Slice(100);
early.Devices[0].Active.Should().BeFalse($"silent slice {i}: not enough of them yet");
early.Health.XInputSilent.Should().Be(i);
}
backend.Send(_deviceA, 0, 200);
InputSlice slice = reader.Slice(100);
slice.Health.XInputSilent.Should().Be(InputReader.SilentBeforeFallback);
slice.Devices.Should().ContainSingle().Which.Active.Should().BeTrue("XInput has never once been seen to move, and the device keeps saying something new");
backend.Send(_deviceA, 0, 200);
reader.Slice(100).Devices[0].Active.Should().BeFalse("the same report again is a pad at rest");
}
[Fact]
public void WhereXInputHasBeenSeenToMoveTheDevicesReportsNeverStandInForIt()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[0] = _atRest;
backend.Arrive(_deviceA, _xboxUsb);
backend.Send(_deviceA, 0, 1);
reader.Slice(100);
// XInput moves: it answers this program. The slice it moved in and the one after are not silent ones.
backend.Pads[0] = _atRest with { Packet = 9, ThumbLx = 3000 };
backend.Send(_deviceA, 0, 2);
reader.Slice(100).Health.XInputSilent.Should().Be(0);
backend.Send(_deviceA, 0, 3);
reader.Slice(100).Health.XInputSilent.Should().Be(0, "the report may be the one XInput already answered for");
// From here the device's reports change - a stick that drifts - and XInput's packet stays: counted, never used.
for (int i = 0; i < InputReader.SilentBeforeFallback + 5; i++)
{
backend.Send(_deviceA, 0, (byte)(10 + i));
reader.Slice(100).Devices[0].Active.Should().BeFalse("XInput is the one to say, and it says at rest");
}
reader.Slice(100).Health.XInputSilent.Should().Be(InputReader.SilentBeforeFallback + 5);
}
[Fact]
public void ASliceInWhichXInputSaysThePadIsInUseIsNotASilentOne()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[0] = _buttonDown;
backend.Arrive(_deviceA, _xboxUsb);
backend.Send(_deviceA, 0, 1);
reader.Slice(100);
backend.Send(_deviceA, 0, 2);
InputSlice slice = reader.Slice(100);
slice.Health.XInputSilent.Should().Be(0, "a button held gives the same packet number and a pad in use");
slice.Devices[0].Active.Should().BeTrue();
}
[Fact]
public void AFaultIsCountedAndANegativeElapsedTimeIsNone()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.ThrowOnDrain = true;
Action slice = () => reader.Slice(100);
slice.Should().Throw<InvalidOperationException>("the reader does not hide a failure; the hub counts it");
reader.Fault();
backend.ThrowOnDrain = false;
InputSlice after = reader.Slice(-5);
after.ElapsedMs.Should().Be(0);
after.Health.Faults.Should().Be(1);
after.Health.Slices.Should().Be(2);
}
[Fact]
public void ARegistrationWindowsRefusedIsSaidInEverySlice()
{
using var backend = new FakeInputBackend { Registers = false };
var reader = new InputReader(backend);
reader.Open();
InputHealth health = reader.Slice(100).Health;
health.RawInputRegistered.Should().BeFalse();
health.Sources().Should().Be("xinput+lastinput");
}
[Fact]
public void WhatADescriptionSaysOfADevice()
{
_steamPad.IsVirtual.Should().BeTrue();
_xboxUsb.IsVirtual.Should().BeFalse();
_dualSenseBluetooth.IsDualSense.Should().BeTrue();
_dualShock.IsDualSense.Should().BeFalse();
(_dualSenseUsb with { XInputClass = true }).IsDualSense.Should().BeFalse("presented through XInput, it is one of XInput's pads");
}
}
@@ -0,0 +1,41 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FluentAssertions;
using FrameLedger.Domain.Input;
namespace FrameLedger.Domain.Tests.Input;
/// <summary>
/// The two facts taken from the name Windows gives a controller's device interface (<c>21_INPUT_DEVICES</c> §What is
/// never read). The names here have the shape Windows writes; their instance parts are made up.
/// </summary>
public sealed class RawDeviceNameTests
{
private const string _xboxUsb = @"\\?\HID#VID_045E&PID_0B12&IG_00#8&1a2b3c4d&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}";
private const string _xboxBluetooth = @"\\?\HID#{00001812-0000-1000-8000-00805f9b34fb}&Dev&VID_045e&PID_0b13&REV_0520&IG_00#9&2b3c4d5e&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}";
private const string _dualSenseUsb = @"\\?\HID#VID_054C&PID_0CE6&MI_03#8&3c4d5e6f&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}";
private const string _dualSenseBluetooth = @"\\?\HID#{00001124-0000-1000-8000-00805F9B34FB}_VID&0002054c_PID&0ce6#8&4d5e6f70&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}";
[Theory]
[InlineData(_xboxUsb, true)]
[InlineData(_xboxBluetooth, true)]
[InlineData(@"\\?\hid#vid_28de&pid_11ff&ig_00#7&5e6f7081&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}", true)]
[InlineData(_dualSenseUsb, false)]
[InlineData(_dualSenseBluetooth, false)]
[InlineData("", false)]
[InlineData(null, false)]
public void ADeviceWindowsPresentsThroughXInputCarriesMicrosoftsMarkInItsName(string? name, bool xinput) =>
RawDeviceName.IsXInputClass(name).Should().Be(xinput);
[Theory]
[InlineData(_xboxUsb, ControllerConnection.Usb)]
[InlineData(_dualSenseUsb, ControllerConnection.Usb)]
[InlineData(_dualSenseBluetooth, ControllerConnection.Bluetooth)] // classic Bluetooth's HID service
[InlineData(_xboxBluetooth, ControllerConnection.Bluetooth)] // low energy's, which also carries VID_
[InlineData(@"\\?\HID#SOMETHING_ELSE#1&2&3#{4d1e55b2-f16f-11cf-88cb-001111000030}", ControllerConnection.Unknown)]
[InlineData("", ControllerConnection.Unknown)]
[InlineData(null, ControllerConnection.Unknown)]
public void TheConnectionIsBluetoothByTheServicesIdentifierAndUsbByAUsbVendorId(string? name, ControllerConnection connection) =>
RawDeviceName.ConnectionOf(name).Should().Be(connection);
}
@@ -28,6 +28,11 @@
<Using Include="Xunit" />
</ItemGroup>
<!-- Windows as the input reader asks it, with every answer written by the test (D157): shared with the other suites that drive the reader. -->
<ItemGroup>
<Compile Include="..\Shared\FakeInputBackend.cs" Link="Shared\FakeInputBackend.cs" />
</ItemGroup>
<!--
GuardMirrorTests and RulesPathAgreementTests P/Invoke into the real
FrameLedger.Guard.dll, which NativeAntiCheatGuard loads by absolute path from
@@ -0,0 +1,276 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Diagnostics;
using FluentAssertions;
using FrameLedger.Application.Capture;
using FrameLedger.Application.Input;
using FrameLedger.Application.Telemetry;
using FrameLedger.Infrastructure.Input;
using FrameLedger.Testing;
namespace FrameLedger.Infrastructure.Tests.Input;
/// <summary>
/// The Agent's one input reader and the sessions' views of it (<c>21_INPUT_DEVICES</c> §The reader): it runs only
/// while a view is open, each view counts the slices in which its own game was in front, a pause is not observed, and
/// a reader that keeps failing ends its run with one line and takes no session with it. The Windows behind it is the
/// tests' own.
/// </summary>
public sealed class InputDeviceHubTests
{
private static readonly TimeSpan _slice = TimeSpan.FromMilliseconds(5);
private static readonly TimeSpan _patience = TimeSpan.FromSeconds(10);
private static GameProcess Pids(params int[] pids) => GameProcess.Unpinned([.. pids.Select(static p => new GameProcessId(p, DateTimeOffset.UnixEpoch))]);
/// <summary>Reads the view until <paramref name="enough"/> says so, adding up what it returned.</summary>
private static (int Span, int Observed, int Foreground, int Controller, long Slices) ReadUntil(IInputActivitySource view, Func<(int Span, int Observed, int Foreground, int Controller, long Slices), bool> enough)
{
(int Span, int Observed, int Foreground, int Controller, long Slices) sum = default;
var clock = Stopwatch.StartNew();
while (!enough(sum) && clock.Elapsed < _patience)
{
if (view.TryRead(out InputReading? reading))
{
sum = (sum.Span + reading.SpanMs, sum.Observed + reading.ObservedMs, sum.Foreground + reading.ForegroundMs, sum.Controller + reading.ControllerMs, reading.Health.Slices);
}
else
{
Thread.Sleep(2);
}
}
return sum;
}
private static int Count(List<string> notes)
{
lock (notes)
{
return notes.Count;
}
}
private static void WaitUntil(Func<bool> condition)
{
var clock = Stopwatch.StartNew();
while (!condition() && clock.Elapsed < _patience)
{
Thread.Sleep(2);
}
condition().Should().BeTrue("it should have happened within the patience of the test");
}
[Fact]
public void WithNoViewTheHubHasNoThreadAndMakesNoBackend()
{
int made = 0;
using var hub = new InputDeviceHub(
() =>
{
made++;
return new FakeInputBackend();
},
interval: _slice);
hub.IsRunning.Should().BeFalse("with no session nothing is read: no thread, no window, no registration");
made.Should().Be(0);
}
[Fact]
public void AViewCountsTheSlicesItsOwnGameWasInFrontOfAndAnotherViewItsOwn()
{
using var backend = new FakeInputBackend { Foreground = 500 };
backend.Pads[0] = new XInputReading(1, Buttons: 0x1000, 0, 0, 0, 0, 0, 0);
backend.Details[0] = new XInputDetails(Wireless: false, BatteryType: 1, BatteryLevel: 0);
using var hub = new InputDeviceHub(() => backend, interval: _slice);
using IInputActivitySource mine = hub.Open();
using IInputActivitySource other = hub.Open();
mine.Follow(Pids(400, 500));
other.Follow(Pids(600));
(int span, int observed, int foreground, int controller, long slices) = ReadUntil(mine, static s => s.Controller > 0 && s.Slices >= 3);
(int otherSpan, int otherObserved, int otherForeground, int otherController, _) = ReadUntil(other, static s => s.Slices >= 3);
hub.IsRunning.Should().BeTrue();
backend.Opened.Should().BeTrue();
slices.Should().BeGreaterThanOrEqualTo(3);
foreground.Should().BeGreaterThan(0).And.BeLessThanOrEqualTo(observed);
controller.Should().BeGreaterThan(0).And.BeLessThanOrEqualTo(foreground);
observed.Should().BeLessThanOrEqualTo(span);
otherObserved.Should().BeGreaterThan(0, "the other session is observed too");
otherSpan.Should().BeGreaterThan(0);
otherForeground.Should().Be(0, "its game was never in front");
otherController.Should().Be(0, "a controller in use while another program is in front is not that session's");
}
[Fact]
public void APinnedProcessIsTheSessionsGame()
{
using var backend = new FakeInputBackend { Foreground = 77 };
using var hub = new InputDeviceHub(() => backend, interval: _slice);
using IInputActivitySource view = hub.Open();
view.Follow(GameProcess.Pinned(77, NSubstitute.Substitute.For<ITargetLiveness>()));
ReadUntil(view, static s => s.Foreground > 0).Foreground.Should().BeGreaterThan(0);
}
[Fact]
public void WithNoWindowInFrontNoSessionIsInFront()
{
using var backend = new FakeInputBackend { Foreground = 0 };
using var hub = new InputDeviceHub(() => backend, interval: _slice);
using IInputActivitySource view = hub.Open();
view.Follow(Pids(0));
(_, int observed, int foreground, _, _) = ReadUntil(view, static s => s.Slices >= 3);
observed.Should().BeGreaterThan(0);
foreground.Should().Be(0, "pid 0 is Windows' word for no window in front, never a game");
}
[Fact]
public void WhileRecordingIsPausedASliceIsNotObserved()
{
bool paused = true;
using var backend = new FakeInputBackend { Foreground = 500 };
using var hub = new InputDeviceHub(() => backend, () => Volatile.Read(ref paused), _slice);
using IInputActivitySource view = hub.Open();
view.Follow(Pids(500));
(int span, int observed, _, _, _) = ReadUntil(view, static s => s.Slices >= 3);
observed.Should().Be(0, "a pause is a gap");
span.Should().BeGreaterThan(0, "the clock does not stop for a pause: a battery level is timed by it");
Volatile.Write(ref paused, false);
ReadUntil(view, static s => s.Observed > 0).Observed.Should().BeGreaterThan(0);
}
[Fact]
public void TheRunEndsWithItsLastViewAndANewViewStartsANewOne()
{
var made = new List<FakeInputBackend>();
var notes = new List<string>();
using var hub = new InputDeviceHub(
() =>
{
var backend = new FakeInputBackend();
lock (made)
{
made.Add(backend);
}
return backend;
},
interval: _slice,
note: line =>
{
lock (notes)
{
notes.Add(line);
}
});
IInputActivitySource first = hub.Open();
ReadUntil(first, static s => s.Slices >= 2);
first.Dispose();
// The run's last act is its line in the log: by then the backend is disposed and the thread's slot is free.
WaitUntil(() => Count(notes) == 1);
hub.IsRunning.Should().BeFalse();
lock (made)
{
made.Should().ContainSingle().Which.Disposed.Should().BeTrue("the window and the registration go with the last session");
}
lock (notes)
{
notes.Should().ContainSingle().Which.Should().StartWith("input: run ended - slices ").And.Contain("raw input registered").And.Contain("xinput there").And.Contain("last input read");
}
using IInputActivitySource second = hub.Open();
ReadUntil(second, static s => s.Slices >= 1).Slices.Should().BeGreaterThanOrEqualTo(1);
lock (made)
{
made.Should().HaveCount(2, "a new session opens a new run, with a backend of its own");
}
}
[Fact]
public void AReaderThatKeepsFailingEndsItsRunWithOneLineAndTheViewSimplyHasNothingMore()
{
var notes = new List<string>();
using var backend = new FakeInputBackend { ThrowOnDrain = true };
using var hub = new InputDeviceHub(() => backend, interval: _slice, note: line =>
{
lock (notes)
{
notes.Add(line);
}
});
using IInputActivitySource view = hub.Open();
WaitUntil(() => Count(notes) == 2);
hub.IsRunning.Should().BeFalse();
view.TryRead(out _).Should().BeFalse("no slice was ever made");
lock (notes)
{
notes.Should().HaveCount(2);
notes[0].Should().StartWith($"input: the reader's slice threw {InputDeviceHub.MaxFaults} times running and the run ends (InvalidOperationException");
notes[1].Should().StartWith("input: run ended");
}
}
[Fact]
public void ABackendThatCannotBeMadeEndsTheRunWithOneLine()
{
var notes = new List<string>();
using var hub = new InputDeviceHub(() => throw new InvalidOperationException("no window station"), interval: _slice, note: line =>
{
lock (notes)
{
notes.Add(line);
}
});
using IInputActivitySource view = hub.Open();
WaitUntil(() => Count(notes) == 2);
hub.IsRunning.Should().BeFalse();
lock (notes)
{
notes[0].Should().Be("input: the reader did not start (InvalidOperationException: no window station)");
}
}
[Fact]
public void ADisposedHubOpensNoViewAndDisposingTwiceIsNothing()
{
using var backend = new FakeInputBackend();
var hub = new InputDeviceHub(() => backend, interval: _slice);
IInputActivitySource view = hub.Open();
ReadUntil(view, static s => s.Slices >= 1);
hub.Dispose();
hub.Dispose();
hub.IsRunning.Should().BeFalse();
Action open = () => hub.Open();
open.Should().Throw<ObjectDisposedException>();
view.Dispose();
}
[Fact]
public void ASliceMustBeLongerThanNothing()
{
Action zero = () => _ = new InputDeviceHub(static () => new FakeInputBackend(), interval: TimeSpan.Zero);
Action none = () => _ = new InputDeviceHub(null!);
zero.Should().Throw<ArgumentOutOfRangeException>();
none.Should().Throw<ArgumentNullException>();
}
}
@@ -0,0 +1,178 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Buffers.Binary;
using FluentAssertions;
using FrameLedger.Application.Input;
using FrameLedger.Infrastructure.Input;
namespace FrameLedger.Infrastructure.Tests.Input;
/// <summary>
/// The bytes <c>GetRawInputBuffer</c> fills, walked (<c>21_INPUT_DEVICES</c> §The reader): each report of each HID block
/// reaches the sink with its device, and a block that claims more than the buffer holds ends the walk without a byte
/// read past it. The buffers are built here to the documented layout - <b>none was filled by Windows</b>.
/// </summary>
public sealed class RawInputBufferTests
{
/// <summary>One block: the header, then for a HID device the size and count of its reports and the reports themselves.</summary>
private static byte[] Block(nint device, int reportBytes, params byte[][] reports)
{
byte[] block = new byte[RawInputBuffer.HeaderBytes + 8 + reports.Sum(static r => r.Length)];
BinaryPrimitives.WriteUInt32LittleEndian(block, RawInputBuffer.TypeHid);
BinaryPrimitives.WriteUInt32LittleEndian(block.AsSpan(4), (uint)block.Length);
BinaryPrimitives.WriteInt64LittleEndian(block.AsSpan(8), device);
BinaryPrimitives.WriteUInt32LittleEndian(block.AsSpan(RawInputBuffer.HeaderBytes), (uint)reportBytes);
BinaryPrimitives.WriteUInt32LittleEndian(block.AsSpan(RawInputBuffer.HeaderBytes + 4), (uint)reports.Length);
int at = RawInputBuffer.HeaderBytes + 8;
foreach (byte[] report in reports)
{
report.CopyTo(block, at);
at += report.Length;
}
return block;
}
/// <summary>Blocks one after another, each starting on a multiple of eight as Windows lays them out.</summary>
private static byte[] Buffer(params byte[][] blocks)
{
var bytes = new List<byte>();
foreach (byte[] block in blocks)
{
bytes.AddRange(block);
while (bytes.Count % 8 != 0)
{
bytes.Add(0xEE);
}
}
return [.. bytes];
}
[Fact]
public void EachReportOfEachBlockReachesTheSinkWithItsDevice()
{
var sink = new Recorder();
byte[] buffer = Buffer(
Block(0x10, 3, [1, 2, 3], [4, 5, 6]),
Block(0x20, 5, [9, 9, 9, 9, 9]));
RawInputBuffer.Walk(buffer, 2, sink).Should().Be(2);
sink.Reports.Should().HaveCount(3);
sink.Reports[0].Should().Be((0x10, "010203"));
sink.Reports[1].Should().Be((0x10, "040506"));
sink.Reports[2].Should().Be((0x20, "0909090909"));
}
[Fact]
public void OnlyAsManyBlocksAsWindowsSaidItWroteAreWalked()
{
var sink = new Recorder();
byte[] buffer = Buffer(Block(0x10, 1, [1]), Block(0x20, 1, [2]));
RawInputBuffer.Walk(buffer, 1, sink).Should().Be(1);
sink.Reports.Should().ContainSingle().Which.Device.Should().Be(0x10);
RawInputBuffer.Walk(buffer, 0, sink).Should().Be(0);
RawInputBuffer.Walk([], 3, sink).Should().Be(0);
}
[Fact]
public void ABlockThatIsNotAHidDevicesIsPassedOver()
{
var sink = new Recorder();
byte[] keyboard = new byte[RawInputBuffer.HeaderBytes + 16];
BinaryPrimitives.WriteUInt32LittleEndian(keyboard, 1);
BinaryPrimitives.WriteUInt32LittleEndian(keyboard.AsSpan(4), (uint)keyboard.Length);
RawInputBuffer.Walk(Buffer(keyboard, Block(0x20, 1, [7])), 2, sink).Should().Be(2);
sink.Reports.Should().ContainSingle("the reader registers for controllers only; a block of another kind is never read").Which.Device.Should().Be(0x20);
}
[Fact]
public void TheLastBlockMayEndTheBufferWithoutItsPadding()
{
var sink = new Recorder();
byte[] block = Block(0x10, 3, [1, 2, 3]);
block.Length.Should().Be(35, "not a multiple of eight: the walk must not want the five bytes after it");
RawInputBuffer.Walk(block, 1, sink).Should().Be(1);
sink.Reports.Should().ContainSingle();
}
/// <summary>The bytes come from a device by way of Windows: no length in them is trusted.</summary>
[Fact]
public void ABlockThatClaimsMoreThanTheBufferHoldsEndsTheWalkAndWhatCameBeforeStands()
{
var sink = new Recorder();
byte[] good = Block(0x10, 2, [1, 2]);
byte[] lying = Block(0x20, 2, [3, 4]);
BinaryPrimitives.WriteUInt32LittleEndian(lying.AsSpan(4), 4096);
RawInputBuffer.Walk(Buffer(good, lying), 2, sink).Should().Be(1);
sink.Reports.Should().ContainSingle().Which.Device.Should().Be(0x10);
}
[Fact]
public void ABlockSmallerThanItsOwnHeaderEndsTheWalk()
{
var sink = new Recorder();
byte[] tiny = Block(0x10, 1, [1]);
BinaryPrimitives.WriteUInt32LittleEndian(tiny.AsSpan(4), 8);
RawInputBuffer.Walk(Buffer(tiny, Block(0x20, 1, [2])), 2, sink).Should().Be(0);
sink.Reports.Should().BeEmpty();
RawInputBuffer.Walk(new byte[10], 1, sink).Should().Be(0, "not even a header");
}
[Theory]
[InlineData(0u, 4u)] // reports of no size
[InlineData(4u, 0u)] // no reports
[InlineData(4u, 3u)] // three reports of four bytes where eight bytes follow
[InlineData(0xFFFFFFFFu, 0xFFFFFFFFu)] // a product that would not fit in 32 bits
public void ReportsThatDoNotFitTheirBlockAreNotHandedOver(uint reportBytes, uint count)
{
var sink = new Recorder();
byte[] block = Block(0x10, 4, [1, 2, 3, 4], [5, 6, 7, 8]);
BinaryPrimitives.WriteUInt32LittleEndian(block.AsSpan(RawInputBuffer.HeaderBytes), reportBytes);
BinaryPrimitives.WriteUInt32LittleEndian(block.AsSpan(RawInputBuffer.HeaderBytes + 4), count);
RawInputBuffer.Walk(Buffer(block, Block(0x20, 1, [9])), 2, sink).Should().Be(2, "the block is walked over by its own size, which is sound");
sink.Reports.Should().ContainSingle("only the block after it").Which.Device.Should().Be(0x20);
}
[Fact]
public void AHidBlockWithNoRoomForItsCountsHasNoReports()
{
var sink = new Recorder();
byte[] header = new byte[RawInputBuffer.HeaderBytes + 4];
BinaryPrimitives.WriteUInt32LittleEndian(header, RawInputBuffer.TypeHid);
BinaryPrimitives.WriteUInt32LittleEndian(header.AsSpan(4), (uint)header.Length);
RawInputBuffer.Walk(header, 1, sink).Should().Be(1);
sink.Reports.Should().BeEmpty();
}
private sealed class Recorder : IInputBackendSink
{
public List<(nint Device, string Hex)> Reports { get; } = [];
public void Arrived(nint device, RawController controller)
{
}
public void Removed(nint device)
{
}
public void Report(nint device, ReadOnlySpan<byte> report) => Reports.Add((device, Convert.ToHexString(report)));
}
}
@@ -0,0 +1,153 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Diagnostics;
using FluentAssertions;
using FrameLedger.Application.Input;
using FrameLedger.Infrastructure.Input;
namespace FrameLedger.Infrastructure.Tests.Input;
/// <summary>
/// The reader's Windows side against the real Windows of whatever machine runs this - a developer's PC with or without
/// a controller, CI's runner with none. It asserts the CONTRACT, never the hardware: it opens, answers every question
/// without throwing, says honestly what it could register, and leaves nothing behind. <b>What it reads from a real
/// controller is not established by this</b>; that is owner-only item 48.
/// </summary>
[Trait("Category", "Integration")]
public sealed class Win32InputBackendTests
{
[Fact]
public void ItOpensAnswersEveryQuestionAndClosesWithOrWithoutAController()
{
using var backend = new Win32InputBackend();
var sink = new Recorder();
// Refused is a valid answer - a session with no interactive desktop gives none - and is said, not hidden.
bool registered = backend.Open();
backend.Drain(sink);
backend.Drain(sink);
for (int slot = 0; slot < InputReader.Slots; slot++)
{
if (backend.TryReadPad(slot, out XInputReading pad))
{
pad.LeftTrigger.Should().BeInRange(0, 255);
backend.TryReadPadDetails(slot, out XInputDetails details).Should().BeTrue("a pad XInput has a state for has capabilities");
details.BatteryType.Should().BeOneOf(0, 1, 2, 3, 0xFF);
}
}
if (backend.TryReadLastInputTick(out uint tick))
{
// The same clock as Environment.TickCount, and never ahead of it by more than a moment.
unchecked((int)((uint)Environment.TickCount - tick)).Should().BeGreaterThan(-60_000);
}
uint front = backend.ForegroundProcessId();
if (front != 0)
{
Action named = () => Process.GetProcessById((int)front).Dispose();
named.Should().NotThrow("what is in front is a live process");
}
backend.ThreadCpuMs().Should().BeGreaterThanOrEqualTo(0);
sink.Reports.Should().BeGreaterThanOrEqualTo(0);
if (!registered)
{
sink.Arrived.Should().Be(0, "nothing is listed for a registration Windows refused");
}
}
[Fact]
public void AReaderOverItTakesSlicesAndSaysWhatAnswered()
{
using var backend = new Win32InputBackend();
var reader = new InputReader(backend);
reader.Open();
InputSlice first = reader.Slice(100);
InputSlice second = reader.Slice(100);
second.Health.Slices.Should().Be(2);
second.Health.Faults.Should().Be(0);
second.Health.ThreadCpuMs.Should().BeGreaterThanOrEqualTo(first.Health.ThreadCpuMs);
second.Health.XInputAvailable.Should().Be(backend.XInputAvailable);
// All(), not OnlyContain: with no controller connected the list is empty, and that is a valid answer.
second.Devices.All(static d => d.Device.Id > 0).Should().BeTrue("every controller it lists has a number");
}
[Fact]
public void TheHubRunsOverItAndEndsCleanly()
{
var notes = new List<string>();
using var hub = new InputDeviceHub(static () => new Win32InputBackend(), interval: TimeSpan.FromMilliseconds(10), note: line =>
{
lock (notes)
{
notes.Add(line);
}
});
IInputActivitySource view = hub.Open();
var clock = Stopwatch.StartNew();
InputReading? reading = null;
while (reading is null && clock.Elapsed < TimeSpan.FromSeconds(10))
{
if (!view.TryRead(out reading))
{
Thread.Sleep(5);
}
}
view.Dispose();
reading.Should().NotBeNull("the reader's thread made a slice");
reading.SpanMs.Should().BeGreaterThanOrEqualTo(0);
reading.ForegroundMs.Should().Be(0, "this view followed no process");
lock (notes)
{
notes.Should().NotContain(static n => n.Contains("did not start", StringComparison.Ordinal) || n.Contains("threw", StringComparison.Ordinal));
}
}
[Fact]
public void ItCanBeOpenedAgainAfterItWasClosedAndClosedTwice()
{
var first = new Win32InputBackend();
bool registered = first.Open();
first.Dispose();
first.Dispose();
using var second = new Win32InputBackend();
second.Open().Should().Be(registered, "the window's class and the registration were given back");
Action reopen = () => first.Open();
reopen.Should().Throw<ObjectDisposedException>();
}
[Fact]
public void BeforeItIsOpenedItHandsOverNothing()
{
using var backend = new Win32InputBackend();
var sink = new Recorder();
backend.Drain(sink);
sink.Arrived.Should().Be(0);
sink.Reports.Should().Be(0);
}
private sealed class Recorder : IInputBackendSink
{
public int Arrived { get; private set; }
public int Reports { get; private set; }
void IInputBackendSink.Arrived(nint device, RawController controller) => Arrived++;
public void Removed(nint device)
{
}
public void Report(nint device, ReadOnlySpan<byte> report) => Reports++;
}
}
+90
View File
@@ -0,0 +1,90 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FrameLedger.Application.Input;
namespace FrameLedger.Testing;
/// <summary>Windows, as the input reader asks it, with every answer written by the test: <b>no device is behind it</b>.</summary>
internal sealed class FakeInputBackend : IInputBackend
{
private readonly List<Action<IInputBackendSink>> _pending = [];
public bool Registers { get; set; } = true;
public bool XInputAvailable { get; set; } = true;
/// <summary>The pads XInput has, by slot.</summary>
public Dictionary<int, XInputReading> Pads { get; } = [];
public Dictionary<int, XInputDetails> Details { get; } = [];
/// <summary>Windows' time of the last keyboard or mouse input; null is "Windows did not give it".</summary>
public uint? LastInputTick { get; set; } = 1000;
public uint Foreground { get; set; } = 42;
public long CpuMs { get; set; }
public bool ThrowOnDrain { get; set; }
/// <summary>How many times each slot was asked for its state.</summary>
public int[] PadAsks { get; } = new int[InputReader.Slots];
public int DetailAsks { get; private set; }
public bool Opened { get; private set; }
public bool Disposed { get; private set; }
public void Arrive(nint device, RawController controller) => _pending.Add(sink => sink.Arrived(device, controller));
public void Leave(nint device) => _pending.Add(sink => sink.Removed(device));
public void Send(nint device, params byte[] report) => _pending.Add(sink => sink.Report(device, report));
public bool Open()
{
Opened = true;
return Registers;
}
public void Drain(IInputBackendSink sink)
{
if (ThrowOnDrain)
{
throw new InvalidOperationException("the drain failed");
}
foreach (Action<IInputBackendSink> step in _pending)
{
step(sink);
}
_pending.Clear();
}
public bool TryReadPad(int slot, out XInputReading pad)
{
PadAsks[slot]++;
return Pads.TryGetValue(slot, out pad);
}
public bool TryReadPadDetails(int slot, out XInputDetails details)
{
DetailAsks++;
return Details.TryGetValue(slot, out details);
}
public bool TryReadLastInputTick(out uint tick)
{
tick = LastInputTick ?? 0;
return LastInputTick is not null;
}
public uint ForegroundProcessId() => Foreground;
public long ThreadCpuMs() => CpuMs;
public void Dispose() => Disposed = true;
}
+33
View File
@@ -0,0 +1,33 @@
# The Windows functions the input reader calls (docs/21_INPUT_DEVICES.md, owner decisions D155-D163).
# One name a line. tools/input-readonly-check.ps1 holds this list to src/FrameLedger.Infrastructure/Input/Win32Input.cs
# in both directions, and refuses a name that sends to a device, injects input or reads a key whatever this file says.
# Raw input for game controllers: their reports while the Agent is in the background, who arrived and left, and what
# a device is by its two USB ids. It opens no device.
RegisterRawInputDevices
GetRawInputBuffer
GetRawInputData
GetRawInputDeviceInfoW
GetRawInputDeviceList
# XInput: a pad's state, whether it is wireless, its battery. Getters only.
XInputGetState
XInputGetCapabilities
XInputGetBatteryInformation
# Keyboard and mouse: the time of the last input, and nothing else (D158).
GetLastInputInfo
# The window raw input is delivered to: never shown, a child of HWND_MESSAGE, answered by the default procedure.
RegisterClassExW
UnregisterClassW
CreateWindowExW
DestroyWindow
DefWindowProcW
PeekMessageW
DispatchMessageW
GetModuleHandleW
# The reader's own cost: the processor time its thread used.
GetCurrentThread
GetThreadTimes
+287
View File
@@ -0,0 +1,287 @@
# SPDX-License-Identifier: GPL-3.0-only
# Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
#Requires -Version 7.0
<#
.SYNOPSIS
What FrameLedger asks Windows about controllers, the keyboard and the mouse is a committed list of calls, none of
which sends anything to a device or reads a key.
.DESCRIPTION
docs/21_INPUT_DEVICES.md makes three promises a reviewer would otherwise have to check by reading (owner decisions
D155-D163, 2026-11-14):
- keyboard and mouse are known only by the time of the last input: no key, no button, no position is ever read,
and no hook is installed (D158);
- nothing is ever sent to a controller: no output report, no feature-report request, no vibration (D159);
- controllers are read by the Agent from outside the game: the code loaded into a game reads no input (D155).
The legal texts say the same to the user. A sentence does not keep itself true; this does.
WHAT IT HOLDS:
1. every Windows function declared in src/FrameLedger.Infrastructure/Input/Win32Input.cs - the one file the
input reader's calls are declared in - is on tools/input-allowed-calls.txt, and every name there is declared
(a list longer than the code is a list nobody reads);
2. no name on the list is one that writes to a device, injects input or reads a key - whatever the list says.
This rule judges the LIST, so the way to let such a call in is not "add a line to the text file";
3. no managed source outside src/FrameLedger.Infrastructure/Input/ names an input function at all, and none
anywhere - nor NativeMethods.txt, where CsWin32 would be asked for one - names a forbidden one;
4. raw input is registered for joysticks and gamepads only: InputReader.RegisteredUsages is exactly usage page 1,
usages 4 and 5, and the registration is built from it and from nothing else;
5. no native source (src/native, the vendored code aside) names an input function: nothing loaded into a game,
and no other native binary, reads input.
WHAT IT DOES NOT DO. It reads names, not behaviour: it cannot tell what a call is used for. It does not look at
the tests, which may drive a real keyboard to test the App's own shortcuts. Comments and string literals are taken
out first, so a function named in the comment that says it is never called is not a call.
-SelfTest proves every rule in both directions on in-memory sources.
#>
[CmdletBinding()]
param(
[string]$RepoRoot = (Split-Path $PSScriptRoot -Parent),
[switch]$SelfTest
)
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
# The names of Windows' input functions, as tokens. XInput's functions are XInputGet*, XInputSet* and XInputEnable;
# the project's own types are XInputReading, XInputPad and the like, and are not these.
$script:InputCall = '\b(XInput(?:Get|Set|Enable)[A-Za-z]*|GetRawInput[A-Za-z]*|RegisterRawInputDevices|GetRegisteredRawInputDevices|GetLastInputInfo|HidD_\w+|HidP_\w+|SendInput|keybd_event|mouse_event|GetAsyncKeyState|GetKeyState|GetKeyboardState|GetKeyNameText[AW]?|MapVirtualKey(?:Ex)?[AW]?|ToUnicode(?:Ex)?|SetWindowsHookEx[AW]?|BlockInput|DirectInput8Create|GameInputCreate)\b'
# A namespace is not a call, and is refused all the same: its readings stop when the program is not in front, and it
# is not on the list of what was decided (21_INPUT_DEVICES section Rejected).
$script:InputNamespace = 'Windows\.Gaming\.Input'
# What may never be called, on the list or off it. Each with its reason, because a list judged by a pattern nobody
# can read is a list nobody trusts.
$script:Forbidden = [ordered]@{
'^XInputSet' = 'sends to a controller (D159)'
'^XInputEnable$' = 'changes what every XInput call of the process returns'
'^XInputGetKeystroke$' = 'reads which button was pressed, as a key (D158, 21_INPUT_DEVICES section What is never read)'
'^XInputGetAudioDeviceIds$' = 'identifies the audio devices of a headset'
'^XInputGetDSoundAudioDeviceGuids$' = 'identifies the audio devices of a headset'
'^HidD_' = 'opens or talks to a HID device: an output report, a feature report, a serial number (D159)'
'^HidP_' = 'not decided: 21_INPUT_DEVICES reads a DualSense by its own layout and no other HID controller'
'^SendInput$' = 'injects input'
'^keybd_event$' = 'injects input'
'^mouse_event$' = 'injects input'
'^BlockInput$' = 'blocks input'
'^GetAsyncKeyState$' = 'reads a key (D158)'
'^GetKeyState$' = 'reads a key (D158)'
'^GetKeyboardState$' = 'reads every key (D158)'
'^GetKeyNameText' = 'names a key (D158)'
'^MapVirtualKey' = 'translates a key (D158)'
'^ToUnicode' = 'turns keys into text (D158)'
'^SetWindowsHookEx' = 'installs a hook (D158; tools/chokepoint-check.ps1 refuses it as well)'
'^GetRegisteredRawInputDevices$' = 'not needed: the reader knows what it registered'
'^DirectInput8Create$' = 'DirectInput: not decided, and it does not read in the background'
'^GameInputCreate$' = 'GameInput: rejected (21_INPUT_DEVICES section Rejected)'
}
# Source text without its comments and string literals.
function Get-Code([string]$Source) {
$code = [regex]::Replace($Source, '/\*.*?\*/', ' ', 'Singleline')
$code = [regex]::Replace($code, '//[^\r\n]*', ' ')
$code = [regex]::Replace($code, '@"(""|[^"])*"', '""')
return [regex]::Replace($code, '"(\\.|[^"\\\r\n])*"', '""')
}
# The names of the list, and what is wrong with the list itself.
function Read-AllowedList([string]$Text) {
$names = [System.Collections.Generic.List[string]]::new()
$problems = [System.Collections.Generic.List[string]]::new()
$number = 0
foreach ($raw in ($Text -split "`r?`n")) {
$number++
$line = $raw.Trim()
if ($line.Length -eq 0 -or $line.StartsWith('#')) { continue }
if ($line -cnotmatch '^[A-Za-z_]\w*$') { $problems.Add("the list's line $number is not one function name: '$line'"); continue }
if ($names.Contains($line)) { $problems.Add("the list names $line twice"); continue }
$names.Add($line)
}
return @{ Names = @($names); Problems = @($problems) }
}
function Get-ForbiddenReason([string]$Name) {
foreach ($pattern in $script:Forbidden.Keys) {
if ($Name -cmatch $pattern) { return $script:Forbidden[$pattern] }
}
return $null
}
# Every rule, on text. $Declarations is Win32Input.cs; $Managed maps a repository path to a managed source (the
# declarations' own file among them); $NativeMethods is CsWin32's list; $Reader is InputReader.cs; $Backend is
# Win32InputBackend.cs; $Native maps a path to a native source.
function Test-Input([string]$Declarations, [string]$ListText, [hashtable]$Managed, [string]$NativeMethods, [string]$Reader, [string]$Backend, [hashtable]$Native) {
$problems = [System.Collections.Generic.List[string]]::new()
$list = Read-AllowedList $ListText
foreach ($p in $list.Problems) { $problems.Add($p) }
$allowed = $list.Names
# 1. The declarations and the list say the same.
$declared = @([regex]::Matches((Get-Code $Declarations), '\bstatic\s+extern\s+[^;(]*?\b([A-Za-z_]\w*)\s*\(') | ForEach-Object { $_.Groups[1].Value } | Sort-Object -Unique)
if ($declared.Count -eq 0) { $problems.Add('the declarations file declares no function: the check would hold nothing') }
foreach ($name in $declared) {
if ($allowed -cnotcontains $name) { $problems.Add("$name is declared and is not on the list") }
}
foreach ($name in $allowed) {
if ($declared -cnotcontains $name) { $problems.Add("$name is on the list and is not declared: a list longer than the code is a list nobody reads") }
}
# 2. The list itself.
foreach ($name in $allowed) {
$why = Get-ForbiddenReason $name
if ($why) { $problems.Add("$name may not be on the list: it $why") }
}
# 3. The managed sources, and what CsWin32 is asked for.
foreach ($path in ($Managed.Keys | Sort-Object)) {
$code = Get-Code $Managed[$path]
$inReader = $path -like 'src/FrameLedger.Infrastructure/Input/*'
foreach ($m in [regex]::Matches($code, $script:InputCall)) {
$name = $m.Groups[1].Value
$why = Get-ForbiddenReason $name
if ($why) { $problems.Add("$path names ${name}: it $why") }
elseif (-not $inReader) { $problems.Add("$path names ${name}: input is read in src/FrameLedger.Infrastructure/Input/ and nowhere else") }
elseif ($allowed -cnotcontains $name) { $problems.Add("$path names ${name}, which is not on the list") }
}
if ($code -cmatch $script:InputNamespace) { $problems.Add("$path names Windows.Gaming.Input: rejected (21_INPUT_DEVICES section Rejected)") }
}
foreach ($raw in ($NativeMethods -split "`r?`n")) {
$line = $raw.Trim()
if ($line.Length -eq 0 -or $line.StartsWith('//')) { continue }
if ($line -cmatch ('^' + $script:InputCall.Trim('\', 'b') + '$') -or $line -cmatch $script:InputCall) {
$problems.Add("NativeMethods.txt asks CsWin32 for ${line}: the input reader's calls are declared in Win32Input.cs, where this check reads them")
}
}
# 4. What raw input is registered for.
$readerCode = Get-Code $Reader
if ($readerCode -cnotmatch 'RegisteredUsages\s*\{\s*get;\s*\}\s*=\s*\[\s*\(\s*1\s*,\s*4\s*\)\s*,\s*\(\s*1\s*,\s*5\s*\)\s*\]\s*;') {
$problems.Add('InputReader.RegisteredUsages is not exactly [(1, 4), (1, 5)]: raw input is registered for joysticks and gamepads only - usage 2 is a mouse and 6 a keyboard (D158)')
}
$backendCode = Get-Code $Backend
if ($backendCode -cnotmatch 'InputReader\.RegisteredUsages') { $problems.Add('the backend does not build its registration from InputReader.RegisteredUsages') }
if ($backendCode -cmatch '\bUsage(Page)?\s*=\s*(0x[0-9A-Fa-f]+|\d)') { $problems.Add('the backend registers a usage written as a number: the registration is InputReader.RegisteredUsages and nothing else') }
# 5. The native sources.
foreach ($path in ($Native.Keys | Sort-Object)) {
$code = Get-Code $Native[$path]
foreach ($m in [regex]::Matches($code, $script:InputCall)) {
$problems.Add("$path names $($m.Groups[1].Value): no native code reads input - controllers are read by the Agent, in C#, from outside the game (D155)")
}
}
return @($problems)
}
if ($SelfTest) {
$goodDeclarations = @'
internal static unsafe class Win32Input
{
// XInputSetState is never declared here.
[DllImport("user32.dll")] public static extern int RegisterRawInputDevices(RawInputDevice* devices, uint count, uint size);
[DllImport("user32.dll")] public static extern uint GetRawInputBuffer(void* data, uint* size, uint headerSize);
[DllImport("user32.dll")] public static extern int GetLastInputInfo(LastInputInfo* info);
[DllImport("xinput1_4.dll")] public static extern uint XInputGetState(uint userIndex, XInputState* state);
public struct XInputState { public uint PacketNumber; }
}
'@
$goodList = "# the reader's calls`nRegisterRawInputDevices`nGetRawInputBuffer`nGetLastInputInfo`nXInputGetState`n"
$goodReader = 'public static IReadOnlyList<(ushort UsagePage, ushort Usage)> RegisteredUsages { get; } = [(1, 4), (1, 5)];'
$goodBackend = 'IReadOnlyList<(ushort UsagePage, ushort Usage)> usages = InputReader.RegisteredUsages; devices[i] = new Win32Input.RawInputDevice { UsagePage = usages[i].UsagePage, Usage = usages[i].Usage, Flags = flags }; Win32Input.RegisterRawInputDevices(devices, 2, 16); Win32Input.XInputGetState(0, &state);'
$goodManaged = @{
'src/FrameLedger.Infrastructure/Input/Win32Input.cs' = $goodDeclarations
'src/FrameLedger.Infrastructure/Input/Win32InputBackend.cs' = $goodBackend
'src/FrameLedger.Application/Input/InputReader.cs' = $goodReader + ' public bool XInputAvailable => true; XInputReading r; // GetAsyncKeyState is never called'
'src/FrameLedger.App/Charts/ChartWheel.cs' = '/// <c>GetKeyState</c> reported the machine''s NumLock.' + "`n" + 'var s = "SendInput"; Keyboard.GetKeyStates(Key.A);'
}
$goodNativeMethods = "// the window`nIsWindow`nGetWindowThreadProcessId`n"
$goodNative = @{ 'src/native/FrameLedger.Overlay/src/dllmain.cpp' = '// XInputGetState is the Agent''s to call' + "`n" + 'void Hook() {}' }
function New-Case([string]$Name, [int]$Expect, [hashtable]$Change = @{}) {
$managed = @{}
foreach ($k in $goodManaged.Keys) { $managed[$k] = $goodManaged[$k] }
if ($Change.ContainsKey('Managed')) { foreach ($k in $Change.Managed.Keys) { $managed[$k] = $Change.Managed[$k] } }
$backend = if ($Change.ContainsKey('Backend')) { $Change.Backend } else { $goodBackend }
if ($Change.ContainsKey('Backend')) { $managed['src/FrameLedger.Infrastructure/Input/Win32InputBackend.cs'] = $backend }
return @{
Name = $Name
Expect = $Expect
Declarations = if ($Change.ContainsKey('Declarations')) { $Change.Declarations } else { $goodDeclarations }
List = if ($Change.ContainsKey('List')) { $Change.List } else { $goodList }
Managed = $managed
NativeMethods = if ($Change.ContainsKey('NativeMethods')) { $Change.NativeMethods } else { $goodNativeMethods }
Reader = if ($Change.ContainsKey('Reader')) { $Change.Reader } else { $goodReader }
Backend = $backend
Native = if ($Change.ContainsKey('Native')) { $Change.Native } else { $goodNative }
}
}
$setter = $goodDeclarations.Replace('public struct XInputState', '[DllImport("xinput1_4.dll")] public static extern uint XInputSetState(uint userIndex, void* vibration);' + "`n public struct XInputState")
$cases = @(
(New-Case 'the reader as it is, with the project''s own XInput types and a key function named in comments, passes' 0),
(New-Case 'a declared function that is not on the list FAILS, and so does each source that names it' 3 @{ List = "RegisterRawInputDevices`nGetRawInputBuffer`nGetLastInputInfo`n" }),
(New-Case 'a name on the list that is not declared FAILS' 1 @{ List = $goodList + "GetRawInputDeviceList`n" }),
(New-Case 'a line of the list that is not one name FAILS, and the same name twice' 2 @{ List = $goodList + "Get Raw Input`nXInputGetState`n" }),
(New-Case 'XInputSetState declared and put on the list FAILS twice: the list may not hold it, and the source may not name it' 2 @{ Declarations = $setter; List = $goodList + "XInputSetState`n"; Managed = @{ 'src/FrameLedger.Infrastructure/Input/Win32Input.cs' = $setter } }),
(New-Case 'a declarations file that declares nothing FAILS, with every name of the list then undeclared' 5 @{ Declarations = '// nothing' }),
(New-Case 'a key read anywhere in the managed sources FAILS' 1 @{ Managed = @{ 'src/FrameLedger.App/Services/Shortcut.cs' = 'if (GetAsyncKeyState(0x41) != 0) { }' } }),
(New-Case 'a HID feature report in the reader FAILS' 1 @{ Backend = $goodBackend + ' HidD_GetFeature(handle, buffer, 41);' }),
(New-Case 'an allowed call made outside the reader''s folder FAILS' 1 @{ Managed = @{ 'src/FrameLedger.Agent/Program.cs' = 'XInputGetState(0, &state);' } }),
(New-Case 'a call in the reader''s folder that is not on the list FAILS' 1 @{ Backend = $goodBackend + ' Win32Input.GetRawInputDeviceList(null, &n, 16);' }),
(New-Case 'Windows.Gaming.Input named in a source FAILS' 1 @{ Managed = @{ 'src/FrameLedger.Infrastructure/Input/Wgi.cs' = 'using Windows.Gaming.Input;' } }),
(New-Case 'an input function asked of CsWin32 FAILS' 1 @{ NativeMethods = $goodNativeMethods + "XInputGetState`n" }),
(New-Case 'a keyboard added to what raw input is registered for FAILS' 1 @{ Reader = $goodReader.Replace('(1, 5)]', '(1, 5), (1, 6)]') }),
(New-Case 'a backend that registers a usage written as a number FAILS' 1 @{ Backend = $goodBackend.Replace('Usage = usages[i].Usage', 'Usage = 6') }),
(New-Case 'a backend that does not use the registered usages FAILS' 1 @{ Backend = 'devices[i] = new Win32Input.RawInputDevice { UsagePage = page, Usage = usage };' }),
(New-Case 'an input function in the code loaded into a game FAILS' 1 @{ Native = @{ 'src/native/FrameLedger.Overlay/src/dllmain.cpp' = 'XINPUT_STATE s; XInputGetState(0, &s);' } }),
(New-Case 'a hook named in a native source FAILS' 1 @{ Native = @{ 'src/native/FrameLedger.Injector/src/injector.cpp' = 'SetWindowsHookExW(WH_KEYBOARD_LL, proc, nullptr, 0);' } })
)
$failed = 0
foreach ($c in $cases) {
$problems = @(Test-Input $c.Declarations $c.List $c.Managed $c.NativeMethods $c.Reader $c.Backend $c.Native)
$ok = $problems.Count -eq $c.Expect
Write-Host (" {0,-4} {1}{2}" -f ($(if ($ok) { 'ok' } else { 'FAIL' })), $c.Name, ($(if (-not $ok) { " -> $($problems.Count): $($problems -join '; ')" } else { '' })))
if (-not $ok) { $failed++ }
}
if ($failed -gt 0) { Write-Host "input-readonly-check self-test FAILED ($failed)" -ForegroundColor Red; exit 1 }
Write-Host "input-readonly-check self-test: $($cases.Count) cases, both directions" -ForegroundColor Green
exit 0
}
$declarationsPath = Join-Path $RepoRoot 'src/FrameLedger.Infrastructure/Input/Win32Input.cs'
$backendPath = Join-Path $RepoRoot 'src/FrameLedger.Infrastructure/Input/Win32InputBackend.cs'
$readerPath = Join-Path $RepoRoot 'src/FrameLedger.Application/Input/InputReader.cs'
$listPath = Join-Path $RepoRoot 'tools/input-allowed-calls.txt'
$nativeMethodsPath = Join-Path $RepoRoot 'src/FrameLedger.Infrastructure/NativeMethods.txt'
foreach ($path in $declarationsPath, $backendPath, $readerPath, $listPath, $nativeMethodsPath) {
if (-not (Test-Path -LiteralPath $path)) { Write-Host "INPUT READ-ONLY CHECK FAILED: $path is missing" -ForegroundColor Red; exit 1 }
}
$skip = [regex]'[\\/](bin|obj)[\\/]'
$managed = @{}
foreach ($file in Get-ChildItem -LiteralPath (Join-Path $RepoRoot 'src') -Recurse -File -Filter '*.cs') {
if ($skip.IsMatch($file.FullName) -or $file.FullName -like '*\native\*') { continue }
$managed[[IO.Path]::GetRelativePath($RepoRoot, $file.FullName).Replace('\', '/')] = Get-Content -LiteralPath $file.FullName -Raw
}
$native = @{}
foreach ($file in Get-ChildItem -LiteralPath (Join-Path $RepoRoot 'src/native') -Recurse -File -Include '*.cpp', '*.h', '*.inl', '*.c', '*.hpp') {
if ($file.FullName -like '*\third_party\*') { continue }
$native[[IO.Path]::GetRelativePath($RepoRoot, $file.FullName).Replace('\', '/')] = Get-Content -LiteralPath $file.FullName -Raw
}
if ($managed.Count -eq 0 -or $native.Count -eq 0) { Write-Host 'INPUT READ-ONLY CHECK FAILED: no managed or no native source was found' -ForegroundColor Red; exit 1 }
$listText = Get-Content -LiteralPath $listPath -Raw
$problems = @(Test-Input (Get-Content -LiteralPath $declarationsPath -Raw) $listText $managed (Get-Content -LiteralPath $nativeMethodsPath -Raw) (Get-Content -LiteralPath $readerPath -Raw) (Get-Content -LiteralPath $backendPath -Raw) $native)
if ($problems.Count -gt 0) {
Write-Host 'INPUT READ-ONLY CHECK FAILED:' -ForegroundColor Red
foreach ($p in $problems) { Write-Host " - $p" -ForegroundColor Red }
exit 1
}
$count = (Read-AllowedList $listText).Names.Count
Write-Host "input-readonly-check OK - the input reader declares $count Windows functions, each on the list; none sends to a device, injects input or reads a key; no input function in $($managed.Count) managed sources outside the reader, nor in $($native.Count) native sources" -ForegroundColor Green
exit 0