VirtualDesktop 1.6.5__py3-none-win_amd64.whl

VirtualDesktop/_devices.py

@@ -0,0 +1,335 @@
+"""SetupAPI queries used to detect and validate the virtual display device.
+
+Pure ctypes (no ``pywin32`` dependency at import time) because this code also runs inside
+the *elevated helper process*, where the import surface must stay as small as possible.
+
+Note: property keys below are spelled out as raw ``(fmtid, pid)`` pairs on purpose —
+``DEVPKEY_Device_HardwareIds`` is ``{a45c254e-df1c-4efd-8020-67d146a850e0}, 3`` and
+``DEVPKEY_Device_DriverVersion`` is the same fmtid with property id ``13``.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from ctypes import wintypes
+from dataclasses import dataclass, field
+from typing import Iterable, List, Optional, Sequence
+
+from ._log import get_logger
+from ._winapi import IS_WINDOWS, format_hresult, require_windows
+
+log = get_logger("devices")
+
+__all__ = ["DeviceRecord", "enumerate_display_devices", "find_devices_by_hardware_id", "device_status_summary"]
+
+if IS_WINDOWS:  # pragma: no branch
+    setupapi = ctypes.WinDLL("setupapi", use_last_error=True)
+else:  # pragma: no cover - non-Windows import path
+    setupapi = None
+
+DIGCF_PRESENT = 0x00000002
+DIGCF_ALLCLASSES = 0x00000004
+#: ``SPDRP_*`` property ids.  ``SPDRP_HARDWAREID`` is **1**, not 0 — ``0`` is
+#: ``SPDRP_DEVICEDESC``, and using it returns the human-readable description ("Virtual Display
+#: Driver") instead of the hardware id ("Root\\MttVDD"), which silently defeats every
+#: marker-based device check.
+SPDRP_DEVICEDESC = 0x00000000
+SPDRP_HARDWAREID = 0x00000001
+MAX_DEVICE_ID_LEN = 200
+MAX_PATH = 260
+
+_DEVPKEY_Device_HardwareIds = ("{a45c254e-df1c-4efd-8020-67d146a850e0}", 3)
+_DEVPKEY_Device_DriverVersion = ("{a45c254e-df1c-4efd-8020-67d146a850e0}", 13)
+_DEVPKEY_Device_FriendlyName = ("{a45c254e-df1c-4efd-8020-67d146a850e0}", 14)
+_DEVPKEY_Device_Class = ("{a45c254e-df1c-4efd-8020-67d146a850e0}", 10)
+
+
+class _GUID(ctypes.Structure):
+    _fields_ = [
+        ("Data1", ctypes.c_ulong),
+        ("Data2", ctypes.c_ushort),
+        ("Data3", ctypes.c_ushort),
+        ("Data4", ctypes.c_ubyte * 8),
+    ]
+
+
+class _SP_DEVINFO_DATA(ctypes.Structure):
+    _fields_ = [
+        ("cbSize", wintypes.DWORD),
+        ("ClassGuid", _GUID),
+        ("DevInst", wintypes.DWORD),
+        ("Reserved", ctypes.POINTER(ctypes.c_ulong)),
+    ]
+
+
+class _SP_DEVICE_INTERFACE_DATA(ctypes.Structure):
+    _fields_ = [
+        ("cbSize", wintypes.DWORD),
+        ("InterfaceClassGuid", _GUID),
+        ("Flags", wintypes.DWORD),
+        ("Reserved", ctypes.POINTER(ctypes.c_ulong)),
+    ]
+
+
+if IS_WINDOWS:  # pragma: no branch
+    setupapi.SetupDiGetClassDevsW.argtypes = [
+        ctypes.POINTER(_GUID),
+        ctypes.c_wchar_p,
+        wintypes.HWND,
+        wintypes.DWORD,
+    ]
+    setupapi.SetupDiGetClassDevsW.restype = ctypes.c_void_p  # HDEVINFO
+    setupapi.SetupDiEnumDeviceInfo.argtypes = [
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        ctypes.POINTER(_SP_DEVINFO_DATA),
+    ]
+    setupapi.SetupDiEnumDeviceInfo.restype = wintypes.BOOL
+    setupapi.SetupDiGetDeviceInstanceIdW.argtypes = [
+        ctypes.c_void_p,
+        ctypes.POINTER(_SP_DEVINFO_DATA),
+        ctypes.c_wchar_p,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+    ]
+    setupapi.SetupDiGetDeviceInstanceIdW.restype = wintypes.BOOL
+    setupapi.SetupDiGetDeviceRegistryPropertyW.argtypes = [
+        ctypes.c_void_p,
+        ctypes.POINTER(_SP_DEVINFO_DATA),
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+    ]
+    setupapi.SetupDiGetDeviceRegistryPropertyW.restype = wintypes.BOOL
+    setupapi.SetupDiDestroyDeviceInfoList.argtypes = [ctypes.c_void_p]
+    setupapi.SetupDiDestroyDeviceInfoList.restype = wintypes.BOOL
+    setupapi.SetupDiOpenDevRegKey.argtypes = [
+        ctypes.c_void_p,
+        ctypes.POINTER(_SP_DEVINFO_DATA),
+        wintypes.DWORD,
+        wintypes.DWORD,
+        wintypes.DWORD,
+        wintypes.DWORD,
+    ]
+    setupapi.SetupDiOpenDevRegKey.restype = wintypes.HKEY
+    setupapi.SetupDiGetDevicePropertyW.argtypes = [
+        ctypes.c_void_p,
+        ctypes.POINTER(_SP_DEVINFO_DATA),
+        ctypes.POINTER(_GUID),
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+        wintypes.DWORD,
+    ]
+    setupapi.SetupDiGetDevicePropertyW.restype = wintypes.BOOL
+
+
+def _guid_from_string(text: str) -> _GUID:
+    """Parse a GUID string (with or without braces) into a ``GUID`` struct."""
+    value = text.strip().strip("{}")
+    parts = value.split("-")
+    if len(parts) != 5:
+        raise ValueError(f"not a GUID: {text!r}")
+    guid = _GUID()
+    guid.Data1 = int(parts[0], 16)
+    guid.Data2 = int(parts[1], 16)
+    guid.Data3 = int(parts[2], 16)
+    tail = int(parts[3], 16) << 48 | int(parts[4], 16)
+    for index in range(8):
+        shift = 8 * (7 - index)
+        guid.Data4[index] = (tail >> shift) & 0xFF
+    return guid
+
+
+@dataclass
+class DeviceRecord:
+    instance_id: str = ""
+    description: str = ""
+    friendly_name: str = ""
+    hardware_ids: List[str] = field(default_factory=list)
+    driver_version: str = ""
+    class_name: str = ""
+
+    def matches(self, needle: str) -> bool:
+        haystack = " ".join([self.instance_id, self.description, *self.hardware_ids]).upper()
+        return needle.upper() in haystack
+
+    def to_dict(self) -> dict:
+        return {
+            "instance_id": self.instance_id,
+            "description": self.description,
+            "friendly_name": self.friendly_name,
+            "hardware_ids": list(self.hardware_ids),
+            "driver_version": self.driver_version,
+            "class_name": self.class_name,
+        }
+
+
+def _read_description(hdevinfo, info: _SP_DEVINFO_DATA) -> str:
+    """``SPDRP_DEVICEDESC`` - the human-readable name ("Virtual Display Driver").
+
+    This complements the hardware id ("Root\\MttVDD"): a marker can legitimately match either,
+    and on some machines the description is the only place the vendor string appears.
+    """
+    required = wintypes.DWORD()
+    setupapi.SetupDiGetDeviceRegistryPropertyW(
+        hdevinfo, ctypes.byref(info), SPDRP_DEVICEDESC, None, None, 0, ctypes.byref(required)
+    )
+    if not required.value:
+        return ""
+    buffer = ctypes.create_unicode_buffer(required.value // ctypes.sizeof(ctypes.c_wchar) + 1)
+    if not setupapi.SetupDiGetDeviceRegistryPropertyW(
+        hdevinfo,
+        ctypes.byref(info),
+        SPDRP_DEVICEDESC,
+        None,
+        ctypes.cast(buffer, ctypes.c_void_p),
+        required.value,
+        ctypes.byref(required),
+    ):
+        return ""
+    return buffer.value
+
+
+def _read_hardware_ids(hdevinfo, info: _SP_DEVINFO_DATA) -> List[str]:
+    required = wintypes.DWORD()
+    setupapi.SetupDiGetDeviceRegistryPropertyW(
+        hdevinfo, ctypes.byref(info), SPDRP_HARDWAREID, None, None, 0, ctypes.byref(required)
+    )
+    if not required.value:
+        return []
+    buffer = ctypes.create_unicode_buffer(required.value // ctypes.sizeof(ctypes.c_wchar))
+    if not setupapi.SetupDiGetDeviceRegistryPropertyW(
+        hdevinfo,
+        ctypes.byref(info),
+        SPDRP_HARDWAREID,
+        None,
+        ctypes.cast(buffer, ctypes.c_void_p),
+        required.value,
+        ctypes.byref(required),
+    ):
+        return []
+    raw = buffer[: required.value // ctypes.sizeof(ctypes.c_wchar)]
+    return [item for item in raw.split("\x00") if item]
+
+
+def _read_string_property(hdevinfo, info: _SP_DEVINFO_DATA, fmtid_pid) -> str:
+    fmtid = _guid_from_string(fmtid_pid[0])
+    prop_type = wintypes.DWORD()
+    required = wintypes.DWORD()
+    setupapi.SetupDiGetDevicePropertyW(
+        hdevinfo,
+        ctypes.byref(info),
+        ctypes.byref(fmtid),
+        fmtid_pid[1],
+        ctypes.byref(prop_type),
+        None,
+        0,
+        ctypes.byref(required),
+        0,
+    )
+    if not required.value:
+        return ""
+    buffer = ctypes.create_unicode_buffer(required.value // ctypes.sizeof(ctypes.c_wchar) + 1)
+    if not setupapi.SetupDiGetDevicePropertyW(
+        hdevinfo,
+        ctypes.byref(info),
+        ctypes.byref(fmtid),
+        fmtid_pid[1],
+        ctypes.byref(prop_type),
+        ctypes.cast(buffer, ctypes.c_void_p),
+        required.value,
+        ctypes.byref(required),
+        0,
+    ):
+        return ""
+    return buffer.value
+
+
+def find_devices_by_hardware_id(
+    hardware_ids: Sequence[str], *, class_guid: Optional[str] = None, present_only: bool = False
+) -> List[DeviceRecord]:
+    """Enumerate devices whose hardware id *contains* any of ``hardware_ids``.
+
+    An **empty** ``hardware_ids`` means "every device in scope" (used by the diagnostic
+    report).  A non-empty sequence always filters: returning everything and letting a caller
+    post-filter was a real bug — a caller that forgot to filter would see "device present"
+    for any machine with any device at all.
+    """
+    require_windows("find_devices_by_hardware_id")
+    needles = [h for h in hardware_ids if h]
+    flags = DIGCF_PRESENT if present_only else 0
+    if class_guid:
+        guid = _guid_from_string(class_guid)
+        handle = setupapi.SetupDiGetClassDevsW(ctypes.byref(guid), None, None, flags)
+    else:
+        handle = setupapi.SetupDiGetClassDevsW(None, None, None, DIGCF_ALLCLASSES | flags)
+    if not handle or handle == ctypes.c_void_p(-1).value:
+        log.debug("SetupDiGetClassDevs failed: %s", ctypes.get_last_error())
+        return []
+    try:
+        records: List[DeviceRecord] = []
+        index = 0
+        while True:
+            info = _SP_DEVINFO_DATA()
+            info.cbSize = ctypes.sizeof(_SP_DEVINFO_DATA)
+            if not setupapi.SetupDiEnumDeviceInfo(handle, index, ctypes.byref(info)):
+                break
+            index += 1
+            instance_buffer = ctypes.create_unicode_buffer(MAX_DEVICE_ID_LEN + 1)
+            instance_id = ""
+            if setupapi.SetupDiGetDeviceInstanceIdW(
+                handle, ctypes.byref(info), instance_buffer, MAX_DEVICE_ID_LEN + 1, None
+            ):
+                instance_id = instance_buffer.value
+            hardware = _read_hardware_ids(handle, info)
+            record = DeviceRecord(
+                instance_id=instance_id,
+                description=_read_description(handle, info),
+                hardware_ids=hardware,
+                driver_version=_read_string_property(handle, info, _DEVPKEY_Device_DriverVersion),
+            )
+            if _record_matches(record, needles):
+                records.append(record)
+        return records
+    finally:
+        setupapi.SetupDiDestroyDeviceInfoList(handle)
+
+
+def _record_matches(record: DeviceRecord, needles: Sequence[str]) -> bool:
+    """Match needles against instance id, hardware ids *and* the friendly description.
+
+    The description is included on purpose: ``EnumDisplayDevices`` reports the adapter's
+    description ("Virtual Display Driver") where a display name is expected, so a marker list
+    that only covers hardware ids would miss it in monitors/adapters while still matching in
+    SetupAPI.
+    """
+    if not needles:
+        return True
+    haystack = " ".join(
+        [record.instance_id, record.description, record.friendly_name, *record.hardware_ids]
+    ).upper().replace("/", "\\")
+    return any(needle.upper().replace("/", "\\") in haystack for needle in needles)
+
+
+def enumerate_display_devices() -> List[DeviceRecord]:
+    """All devices in the ``Display`` setup class (used by ``check`` for context)."""
+    return find_devices_by_hardware_id([], class_guid="4d36e968-e325-11ce-bfc1-08002be10318")
+
+
+def device_status_summary(markers: Iterable[str]) -> dict:
+    """Report whether a virtual display device matching ``markers`` is installed."""
+    needles = [m for m in markers if m]
+    records: List[DeviceRecord] = []
+    if IS_WINDOWS:
+        records = find_devices_by_hardware_id(needles or [])
+    matched = [r for r in records if _record_matches(r, needles)]
+    return {
+        "present": bool(matched),
+        "count": len(matched),
+        "devices": [r.to_dict() for r in matched],
+    }