VirtualDesktop 1.6.5__py3-none-win_amd64.whl

VirtualDesktop/_compat.py

@@ -0,0 +1,576 @@
+"""Windows version detection and API-availability fallbacks.
+
+Everything in this project has to behave identically on Windows 10 (1607 through 22H2) and
+Windows 11 (21H2 through 24H2+).  The APIs involved did not all arrive at once, and a few of
+them changed *behaviour* rather than availability:
+
+===========================  ==========================  ==================================
+API / behaviour              First available             Fallback used here
+===========================  ==========================  ==================================
+``SetProcessDpiAwareness``   Win 8.1 (shcore)            ``SetProcessDPIAware`` (Vista+)
+``SetProcessDpiAwareness``   —                           *and* check the HRESULT: on Win 8.1
+``Context`` (pmv2)           Win 10 1703                 it fails with ``E_ACCESSDENIED``
+                                                         once awareness is already set
+``GetDpiForWindow``          Win 10 1607                 ``GetDpiForMonitor`` then the
+                                                         monitor DC's ``LOGPIXELSX``
+``GetDpiForMonitor``         Win 8.1 (shcore)            the monitor DC's ``LOGPIXELSX``
+``DwmGetWindowAttribute``    Vista (dwmapi)              ``GetWindowRect`` fallback
+``PrintWindow`` +            ``PW_RENDERFULLCONTENT``    plain ``PrintWindow``, ``WM_PRINT``,
+``PW_RENDERFULLCONTENT``     Win 8.1                     ``BitBlt``
+``ShellExecuteExW`` runas    Vista                       —
+``CreateDesktopW``           Win 2000                    —
+===========================  ==========================  ==================================
+
+The rule for callers: ask this module, never ``platform.version()`` directly, and never assume
+a *newer* build implies a capability — Windows 10 and Windows 11 both ship builds in which an
+optional API is present but returns a failure code.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+from ctypes import wintypes
+from typing import Optional, Tuple
+
+from ._log import get_logger
+
+log = get_logger("compat")
+
+__all__ = [
+    "WINDOWS_10_1607",
+    "WINDOWS_10_1703",
+    "WINDOWS_10_1809",
+    "WINDOWS_11_21H2",
+    "windows_build",
+    "windows_release",
+    "is_windows_11",
+    "at_least",
+    "describe_windows",
+    "supports_pmv2",
+    "set_process_dpi_awareness",
+    "get_process_dpi_awareness",
+    "dpi_awareness_name",
+    "monitor_dpi_legacy",
+    "window_dpi_compat",
+    "IDDCX_MIN_BUILD",
+    "iddcx_support",
+    "windows_compatibility_report",
+]
+
+#: Build thresholds.  Windows 10 and Windows 11 share the same major version (10.0), so the
+#: build number is the only reliable discriminator — ``platform.release()`` is "10" on both.
+WINDOWS_10_1607 = 14393
+WINDOWS_10_1703 = 15063
+WINDOWS_10_1809 = 17763
+WINDOWS_11_21H2 = 22000
+
+#: ``RtlGetVersion`` is used instead of ``GetVersionExW`` because the latter lies unless the
+#: executable carries a compatibility manifest — a detail that differs between Python builds.
+_RTL_OSVERSIONINFOW_SIZE = 6 * 4 + 128 * 2
+
+
+class _OSVERSIONINFOW(ctypes.Structure):
+    _fields_ = [
+        ("dwOSVersionInfoSize", wintypes.DWORD),
+        ("dwMajorVersion", wintypes.DWORD),
+        ("dwMinorVersion", wintypes.DWORD),
+        ("dwBuildNumber", wintypes.DWORD),
+        ("dwPlatformId", wintypes.DWORD),
+        ("szCSDVersion", ctypes.c_wchar * 128),
+    ]
+
+
+def _rtl_version() -> Optional[Tuple[int, int, int]]:
+    try:
+        ntdll = ctypes.WinDLL("ntdll", use_last_error=True)
+        info = _OSVERSIONINFOW()
+        info.dwOSVersionInfoSize = ctypes.sizeof(_OSVERSIONINFOW)
+        if ntdll.RtlGetVersion(ctypes.byref(info)) != 0:
+            return None
+        return int(info.dwMajorVersion), int(info.dwMinorVersion), int(info.dwBuildNumber)
+    except Exception:  # pragma: no cover - non-Windows / blocked ntdll
+        return None
+
+
+def windows_build() -> int:
+    """The OS build number (``22000``+ on Windows 11, ``10240``..``19045`` on Windows 10)."""
+    version = _rtl_version()
+    if version is not None:
+        return version[2]
+    # ``sys.getwindowsversion()`` is the documented Python accessor and needs no ctypes.
+    try:
+        return int(sys.getwindowsversion().build)
+    except Exception:  # pragma: no cover - non-Windows
+        return 0
+
+
+def windows_release() -> str:
+    """``"11"``, ``"10"``, ``"8.1"`` … — derived from the build, not from ``platform``."""
+    build = windows_build()
+    if build >= WINDOWS_11_21H2:
+        return "11"
+    if build >= 10240:
+        return "10"
+    version = _rtl_version()
+    if version is None:
+        return "unknown"
+    return f"{version[0]}.{version[1]}"
+
+
+def is_windows_11() -> bool:
+    return windows_build() >= WINDOWS_11_21H2
+
+
+def at_least(build: int) -> bool:
+    return windows_build() >= build
+
+
+def describe_windows() -> str:
+    build = windows_build()
+    return f"Windows {windows_release()} (build {build or 'unknown'})"
+
+
+# --------------------------------------------------------------------------------------
+# DPI awareness
+# --------------------------------------------------------------------------------------
+
+#: ``DPI_AWARENESS_CONTEXT`` pseudo-handles.  They are only understood by
+#: ``SetProcessDpiAwarenessContext``, and passing them to the older APIs fails.
+DPI_AWARENESS_CONTEXT_UNAWARE = -1
+DPI_AWARENESS_CONTEXT_SYSTEM_AWARE = -2
+DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE = -3
+DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2 = -4
+DPI_AWARENESS_CONTEXT_UNAWARE_GDISCALED = -5
+
+_SHCORE_PROCESS_DPI_AWARENESS = {
+    -1: 0,  # unaware
+    -2: 1,  # system aware
+    -3: 2,  # per monitor
+    -4: 2,  # per monitor v2 is only expressible through the context API
+}
+_PROCESS_DPI_AWARENESS_NAMES = {0: "unaware", 1: "system-aware", 2: "per-monitor-aware"}
+E_ACCESSDENIED = -2147024891  # 0x80070005, returned as a signed HRESULT by shcore
+
+_user32 = None
+_shcore = None
+
+#: Whether ``SetProcessDpiAwarenessContext`` exists.  ``ctypes`` does **not** expose a
+#: missing export as ``AttributeError`` — it raises ``OSError`` on the first *access* — so
+#: ``hasattr`` alone would answer "yes" on Windows 8.1 and then crash on the call.  The probe
+#: below resolves the symbol once, at import time, and records the truth.
+_HAS_CONTEXT_API = False
+_HAS_AWARENESS_API = False
+if sys.platform == "win32":  # pragma: no branch
+    try:
+        _user32 = ctypes.WinDLL("user32", use_last_error=True)
+        try:
+            _user32.SetProcessDpiAwarenessContext.argtypes = [ctypes.c_void_p]
+            _user32.SetProcessDpiAwarenessContext.restype = wintypes.BOOL
+            _HAS_CONTEXT_API = True
+        except OSError:  # pragma: no cover - Windows 8.1 / 7
+            _HAS_CONTEXT_API = False
+        try:
+            _user32.GetThreadDpiAwarenessContext.argtypes = []
+            _user32.GetThreadDpiAwarenessContext.restype = ctypes.c_void_p
+            _HAS_CONTEXT_API = True
+        except OSError:  # pragma: no cover - pre-1607
+            _HAS_CONTEXT_API = False
+        try:
+            _user32.GetAwarenessFromDpiAwarenessContext.argtypes = [ctypes.c_void_p]
+            _user32.GetAwarenessFromDpiAwarenessContext.restype = ctypes.c_int
+            _HAS_AWARENESS_API = True
+        except OSError:  # pragma: no cover - pre-1607
+            _HAS_AWARENESS_API = False
+        _user32.SetProcessDPIAware.argtypes = []
+        _user32.SetProcessDPIAware.restype = wintypes.BOOL
+    except Exception:  # pragma: no cover - very old user32
+        _user32 = None
+    try:
+        _shcore = ctypes.WinDLL("shcore", use_last_error=True)
+        _shcore.SetProcessDpiAwareness.argtypes = [ctypes.c_int]
+        _shcore.SetProcessDpiAwareness.restype = ctypes.c_long
+        _shcore.GetProcessDpiAwareness.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_int)]
+        _shcore.GetProcessDpiAwareness.restype = ctypes.c_long
+    except Exception:  # pragma: no cover - Windows 8.0 / 7
+        _shcore = None
+
+
+def supports_pmv2() -> bool:
+    """True when ``SetProcessDpiAwarenessContext(PER_MONITOR_AWARE_V2)`` can be called."""
+    return _HAS_CONTEXT_API
+
+
+def set_process_dpi_awareness(awareness: int = DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2) -> dict:
+    """Become DPI aware, trying every API the running build offers, in order.
+
+    Returns ``{"applied": <context|None>, "api": <name|None>, "attempts": [...]}``.  The
+    ``attempts`` list is kept so a caller can log *why* a fallback was taken — the interesting
+    case is Windows 8.1, where ``shcore`` exists but returns ``E_ACCESSDENIED`` once the
+    process awareness has already been set by an earlier call.
+    """
+    result: dict = {"applied": None, "api": None, "attempts": [], "build": windows_build()}
+    if sys.platform != "win32":  # pragma: no cover - Windows-only library
+        return result
+
+    # (1) the modern context API (Win 10 1703+).  Fails on older builds by absence.
+    if supports_pmv2():
+        try:
+            if _user32.SetProcessDpiAwarenessContext(ctypes.c_void_p(awareness)):
+                result.update(applied=awareness, api="SetProcessDpiAwarenessContext")
+                result["attempts"].append({"api": "context", "ok": True})
+                return result
+            result["attempts"].append(
+                {"api": "context", "ok": False, "win32_error": ctypes.get_last_error()}
+            )
+        except Exception as exc:  # noqa: BLE001 - never fatal, always fall through
+            result["attempts"].append({"api": "context", "ok": False, "error": str(exc)[:120]})
+    else:
+        result["attempts"].append({"api": "context", "ok": False, "reason": "not exported"})
+
+    # (2) per-monitor awareness through shcore (Win 8.1+).
+    mapped = _SHCORE_PROCESS_DPI_AWARENESS.get(awareness)
+    if _shcore is not None and mapped is not None:
+        try:
+            code = int(_shcore.SetProcessDpiAwareness(mapped))
+            if code == 0:
+                result.update(applied=awareness, api="SetProcessDpiAwareness")
+                result["attempts"].append({"api": "shcore", "ok": True})
+                return result
+            result["attempts"].append(
+                {
+                    "api": "shcore",
+                    "ok": False,
+                    "hresult": hex(code & 0xFFFFFFFF),
+                    "reason": "already-set" if code == E_ACCESSDENIED else "error",
+                }
+            )
+        except Exception as exc:  # noqa: BLE001
+            result["attempts"].append({"api": "shcore", "ok": False, "error": str(exc)[:120]})
+    else:
+        result["attempts"].append({"api": "shcore", "ok": False, "reason": "unavailable"})
+
+    # (3) the Vista-era call, which is unconditional and always worth attempting.
+    try:
+        if _user32 is not None and _user32.SetProcessDPIAware():
+            result.update(applied=DPI_AWARENESS_CONTEXT_SYSTEM_AWARE, api="SetProcessDPIAware")
+            result["attempts"].append({"api": "legacy", "ok": True})
+            return result
+        result["attempts"].append(
+            {"api": "legacy", "ok": False, "win32_error": ctypes.get_last_error()}
+        )
+    except Exception as exc:  # noqa: BLE001
+        result["attempts"].append({"api": "legacy", "ok": False, "error": str(exc)[:120]})
+    return result
+
+
+def get_process_dpi_awareness() -> Optional[str]:
+    """``"per-monitor-v2"``, ``"per-monitor-aware"``, ``"system-aware"``, ``"unaware"``…
+
+    The subtlety that costs a crash if ignored: ``GetThreadDpiAwarenessContext`` does **not**
+    reliably return one of the documented negative pseudo-handles.  Measured on Windows 11
+    22631 (Python 3.11, unelevated): it returned ``0x6010`` — a real handle.  Interpreting that
+    as a ``DPI_AWARENESS_CONTEXT_*`` constant and de-referencing it is an access violation, so
+    the value is only ever *compared*, never read, and the documented
+    ``GetAwarenessFromDpiAwarenessContext`` supplies the awareness level.
+
+    ``GetAwarenessFromDpiAwarenessContext`` cannot distinguish per-monitor-v1 from v2 (both
+    report ``DPI_AWARENESS_PER_MONITOR_AWARE``), so the v2 pseudo-handle is probed once by
+    *calling* with it and recording the resulting context — a comparison, never a dereference.
+    """
+    if sys.platform != "win32":  # pragma: no cover
+        return None
+    if _user32 is not None and _HAS_CONTEXT_API and _HAS_AWARENESS_API:
+        try:
+            context = int(_user32.GetThreadDpiAwarenessContext() or 0)
+            if context:
+                awareness = int(
+                    _user32.GetAwarenessFromDpiAwarenessContext(ctypes.c_void_p(context))
+                )
+                if awareness >= 0 and awareness != 3:  # 3 = DPI_AWARENESS_INVALID
+                    name = _PROCESS_DPI_AWARENESS_NAMES.get(awareness, f"unknown({awareness})")
+                    if awareness == 2 and _per_monitor_v2_active(context):
+                        return "per-monitor-v2"
+                    return name
+        except Exception:  # pragma: no cover - defensive
+            pass
+    if _shcore is not None:
+        try:
+            value = ctypes.c_int()
+            if _shcore.GetProcessDpiAwareness(None, ctypes.byref(value)) == 0:
+                return _PROCESS_DPI_AWARENESS_NAMES.get(
+                    int(value.value), f"unknown({value.value})"
+                )
+        except Exception:  # pragma: no cover - defensive
+            pass
+    return None
+
+
+def _per_monitor_v2_active(context: int) -> bool:
+    """True when ``context`` is the per-monitor-v2 context.
+
+    Tested by *calling* ``SetThreadDpiAwarenessContext`` with the v2 pseudo-handle: it returns
+    the previous context, so ``previous == current-desired`` iff this thread already holds v2.
+    That is a comparison of two opaque handles — never a de-reference, which is what makes it
+    safe on the builds where the handle is real rather than a pseudo-handle.
+    """
+    if _user32 is None or not _HAS_CONTEXT_API:  # pragma: no cover - pre-1703
+        return False
+    try:
+        _user32.SetThreadDpiAwarenessContext.argtypes = [ctypes.c_void_p]
+        _user32.SetThreadDpiAwarenessContext.restype = ctypes.c_void_p
+        previous = int(
+            _user32.SetThreadDpiAwarenessContext(
+                ctypes.c_void_p(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2)
+            )
+            or 0
+        )
+        if previous:
+            # Put the thread back exactly as it was.
+            _user32.SetThreadDpiAwarenessContext(ctypes.c_void_p(previous))
+        now = int(_user32.GetThreadDpiAwarenessContext() or 0)
+        return bool(now) and now == previous
+    except Exception:  # pragma: no cover - defensive
+        return False
+
+
+def dpi_awareness_name() -> str:
+    return get_process_dpi_awareness() or "unknown"
+
+
+# --------------------------------------------------------------------------------------
+# Per-monitor DPI, the pre-1607 way
+# --------------------------------------------------------------------------------------
+
+
+def window_dpi_compat(hwnd: int, *, fallback: int = 96) -> int:
+    """Effective DPI of ``hwnd``, using whichever accessor the running build provides.
+
+    1. ``GetDpiForWindow`` — Win 10 1607+, and the only one that accounts for a per-monitor-v2
+       window that has been dragged between monitors;
+    2. ``GetDpiForMonitor(MDT_EFFECTIVE_DPI)`` — Win 8.1+, resolved through
+       ``MonitorFromWindow(MONITOR_DEFAULTTONEAREST)``;
+    3. the monitor DC's ``LOGPIXELSX`` — available on every supported build.
+    """
+    if sys.platform != "win32" or not hwnd:  # pragma: no cover - Windows-only library
+        return fallback
+    get_dpi_for_window = None
+    monitor_from_window = None
+    if _user32 is not None:
+        try:
+            get_dpi_for_window = _user32.GetDpiForWindow
+        except (AttributeError, OSError):  # pragma: no cover - pre-1607
+            get_dpi_for_window = None
+        if get_dpi_for_window is not None:
+            try:  # a plain callable (a test double) legitimately has no argtypes
+                get_dpi_for_window.argtypes = [wintypes.HWND]
+                get_dpi_for_window.restype = wintypes.UINT
+            except (AttributeError, TypeError):
+                pass
+        try:
+            monitor_from_window = _user32.MonitorFromWindow
+        except (AttributeError, OSError):  # pragma: no cover - pre-2000
+            monitor_from_window = None
+        if monitor_from_window is not None:
+            try:
+                monitor_from_window.argtypes = [wintypes.HWND, wintypes.DWORD]
+                monitor_from_window.restype = wintypes.HMONITOR
+            except (AttributeError, TypeError):
+                pass
+    if get_dpi_for_window is not None:
+        try:
+            value = int(get_dpi_for_window(wintypes.HWND(hwnd)))
+            if value:
+                return value
+        except Exception:  # noqa: BLE001 - the call itself failed, try the next accessor
+            pass
+    monitor = 0
+    if monitor_from_window is not None:
+        try:
+            monitor = int(monitor_from_window(wintypes.HWND(hwnd), 2) or 0)
+        except Exception:  # noqa: BLE001
+            monitor = 0
+    if monitor and _shcore is not None:
+        try:
+            get_dpi_for_monitor = _shcore.GetDpiForMonitor
+            get_dpi_for_monitor.argtypes = [
+                wintypes.HMONITOR,
+                ctypes.c_int,
+                ctypes.POINTER(wintypes.UINT),
+                ctypes.POINTER(wintypes.UINT),
+            ]
+            x, y = wintypes.UINT(), wintypes.UINT()
+            if get_dpi_for_monitor(
+                wintypes.HMONITOR(monitor), 0, ctypes.byref(x), ctypes.byref(y)
+            ) == 0 and int(x.value):
+                return int(x.value)
+        except Exception:  # noqa: BLE001 - shcore missing (Windows 8.0) or call failed
+            pass
+    if monitor:
+        value = monitor_dpi_legacy(monitor, fallback=fallback)
+        if value:
+            return value
+    return fallback
+
+
+def monitor_dpi_legacy(hmonitor: int, *, fallback: int = 96) -> Optional[int]:
+    """Effective DPI of ``hmonitor`` using only APIs present since Windows 2000.
+
+    ``GetDpiForWindow`` (1607+) and ``GetDpiForMonitor`` (8.1+) are the modern accessors, but
+    neither exists on every supported build.  The device context of a monitor reports
+    ``LOGPIXELSX``, and Windows scales that value with the monitor's DPI setting, so it is a
+    usable last resort.  The DC must be released or GDI leaks one handle per call.
+    """
+    if sys.platform != "win32" or not hmonitor:  # pragma: no cover - Windows-only library
+        return None
+    LOGPIXELSX = 88
+    try:
+        gdi32 = ctypes.WinDLL("gdi32", use_last_error=True)
+        user32 = ctypes.WinDLL("user32", use_last_error=True)
+        user32.GetDC.argtypes = [wintypes.HWND]
+        user32.GetDC.restype = wintypes.HDC
+        user32.ReleaseDC.argtypes = [wintypes.HWND, wintypes.HDC]
+        user32.ReleaseDC.restype = ctypes.c_int
+        gdi32.GetDeviceCaps.argtypes = [wintypes.HDC, ctypes.c_int]
+        gdi32.GetDeviceCaps.restype = ctypes.c_int
+        # A monitor handle is a valid HDC source for GDI; ``GetDC`` accepts it directly.
+        dc = user32.GetDC(wintypes.HWND(hmonitor))
+        if not dc:
+            return None
+        try:
+            value = int(gdi32.GetDeviceCaps(dc, LOGPIXELSX))
+        finally:
+            user32.ReleaseDC(wintypes.HWND(hmonitor), dc)
+        return value or fallback
+    except Exception:  # pragma: no cover - defensive
+        return None
+
+
+# --------------------------------------------------------------------------------------
+# Report
+# --------------------------------------------------------------------------------------
+
+
+def _file_version_dll(path: str) -> Optional[str]:
+    """The ``FileVersion`` resource of a system DLL, or ``None``.
+
+    Read with ``GetFileVersionInfoSizeW``/``GetFileVersionInfoW`` instead of loading the DLL:
+    probing by ``LoadLibrary`` would pull a display-driver framework into the process for no
+    reason, and on a locked-down build it can fail for unrelated policy reasons.
+    """
+    if sys.platform != "win32" or not os.path.isfile(path):  # pragma: no cover - Windows only
+        return None
+    try:
+        version = ctypes.WinDLL("version", use_last_error=True)
+        version.GetFileVersionInfoSizeW.argtypes = [ctypes.c_wchar_p, ctypes.POINTER(wintypes.DWORD)]
+        version.GetFileVersionInfoSizeW.restype = wintypes.DWORD
+        version.GetFileVersionInfoW.argtypes = [
+            ctypes.c_wchar_p, wintypes.DWORD, wintypes.DWORD, ctypes.c_void_p
+        ]
+        version.GetFileVersionInfoW.restype = wintypes.BOOL
+        version.VerQueryValueW.argtypes = [
+            ctypes.c_void_p, ctypes.c_wchar_p, ctypes.POINTER(ctypes.c_void_p),
+            ctypes.POINTER(wintypes.UINT),
+        ]
+        version.VerQueryValueW.restype = wintypes.BOOL
+        handle = wintypes.DWORD()
+        size = version.GetFileVersionInfoSizeW(path, ctypes.byref(handle))
+        if not size:
+            return None
+        buffer = ctypes.create_string_buffer(size)
+        if not version.GetFileVersionInfoW(path, 0, size, buffer):
+            return None
+        pointer = ctypes.c_void_p()
+        length = wintypes.UINT()
+        if not version.VerQueryValueW(buffer, "\\", ctypes.byref(pointer), ctypes.byref(length)):
+            return None
+
+        class _FixedFileInfo(ctypes.Structure):
+            _fields_ = [
+                ("dwSignature", wintypes.DWORD),
+                ("dwStrucVersion", wintypes.DWORD),
+                ("dwFileVersionMS", wintypes.DWORD),
+                ("dwFileVersionLS", wintypes.DWORD),
+            ]
+
+        info = ctypes.cast(pointer, ctypes.POINTER(_FixedFileInfo)).contents
+        ms, ls = int(info.dwFileVersionMS), int(info.dwFileVersionLS)
+        return f"{ms >> 16}.{ms & 0xFFFF}.{ls >> 16}.{ls & 0xFFFF}"
+    except Exception:  # pragma: no cover - defensive
+        return None
+
+
+#: The virtual display driver is an IddCx (indirect display) driver.  ``IddCx0102`` in its INF
+#: means the UMDF extension interface version 1.2, which ships with Windows 10 1809 (build
+#: 17763).  Windows 10 1709 and earlier have no IddCx at all, so no indirect display driver can
+#: load there — that is a hard platform floor, not a tunable.
+IDDCX_MIN_BUILD = WINDOWS_10_1809
+
+
+def iddcx_support() -> dict:
+    """Whether this build can host an IddCx indirect display driver, and why.
+
+    Two independent signals, because either can be missing on its own:
+
+    * the build number (``IddCx`` appeared in Windows 10 1703 and the 1.2 interface used by the
+      driver's INF in 1809);
+    * the ``IddCx.dll`` file version actually present in ``System32``.
+    """
+    system_root = os.environ.get("SystemRoot", r"C:\Windows")
+    candidates = [
+        os.path.join(system_root, "System32", "drivers", "UMDF", "IddCx.dll"),
+        os.path.join(system_root, "System32", "IddCx.dll"),
+    ]
+    found = next((path for path in candidates if os.path.isfile(path)), None)
+    version = _file_version_dll(found) if found else None
+    return {
+        "build": windows_build(),
+        "min_build": IDDCX_MIN_BUILD,
+        "build_ok": windows_build() >= IDDCX_MIN_BUILD,
+        "dll_present": bool(found),
+        "dll_path": found,
+        "dll_version": version,
+        "supported": windows_build() >= IDDCX_MIN_BUILD,
+    }
+
+
+def windows_compatibility_report() -> dict:
+    """Everything a bug report needs: build, awareness and which optional APIs are present."""
+    report: dict = {
+        "release": windows_release(),
+        "build": windows_build(),
+        "is_windows_11": is_windows_11(),
+        "described": describe_windows(),
+        "python": sys.version.split()[0],
+        "dpi_awareness": get_process_dpi_awareness(),
+        "thresholds": {
+            "windows_10_1607": WINDOWS_10_1607,
+            "windows_10_1703": WINDOWS_10_1703,
+            "windows_10_1809": WINDOWS_10_1809,
+            "windows_11_21h2": WINDOWS_11_21H2,
+        },
+        "capabilities": {},
+    }
+    if sys.platform != "win32":  # pragma: no cover
+        return report
+    checks = {
+        "SetProcessDpiAwarenessContext": ("user32", "SetProcessDpiAwarenessContext"),
+        "SetProcessDpiAwareness": ("shcore", "SetProcessDpiAwareness"),
+        "GetDpiForWindow": ("user32", "GetDpiForWindow"),
+        "GetDpiForMonitor": ("shcore", "GetDpiForMonitor"),
+        "DwmGetWindowAttribute": ("dwmapi", "DwmGetWindowAttribute"),
+        "PrintWindow": ("user32", "PrintWindow"),
+        "ShellExecuteExW": ("shell32", "ShellExecuteExW"),
+        "CreateDesktopW": ("user32", "CreateDesktopW"),
+    }
+    for label, (library, symbol) in checks.items():
+        try:
+            module = ctypes.WinDLL(library, use_last_error=True)
+            # Accessing a missing export raises OSError, not AttributeError, so probe by
+            # resolving the symbol rather than by ``hasattr``.
+            getattr(module, symbol)
+            report["capabilities"][label] = True
+        except Exception:  # noqa: BLE001
+            report["capabilities"][label] = False
+    return report