DXGKDDI_GETDISPLAYSTATEINTRUSIVE回调函数 (dispmprt.h)

项目
08/07/2023

操作系统 (OS) 调用显示微型端口驱动程序的 DxgkDdiGetDisplayStateNonIntrusive 例程，以从驱动程序收集显示状态信息。

语法

DXGKDDI_GETDISPLAYSTATEINTRUSIVE DxgkddiGetdisplaystateintrusive;

NTSTATUS DxgkddiGetdisplaystateintrusive(
  [in]     HANDLE Context,
  [in/out] PDXGKARG_GETDISPLAYSTATEINTRUSIVE pArgs
)
{...}

参数

[in] Context

指向 DxgkDdiQueryInterface 返回的专用上下文的指针。

[in/out] pArgs

指向 DXGKARG_GETDISPLAYSTATEINTRUSIVE 结构的指针。

返回值

如果成功，DxgkDdiGetDisplayStateIntrusive 将返回STATUS_SUCCESS。否则，它将返回如下所示的错误代码之一。

错误代码	含义
STATUS_DRIVER_INTERNAL_ERROR	驱动程序内发生一般软件错误。
STATUS_ACCESS_DENIED	硬件当前正由其他线程使用，此 DDI 无法访问它。
STATUS_DEVICE_HARDWARE_ERROR	发生一般 HW 错误。
STATUS_DEVICE_POWERED_OFF	设备已关闭电源。

注解

当用户已处于错误状态时，OS 会调用 DxgkDdiGetDisplayStateIntrusive 从驱动程序收集显示状态信息。与 DxgkDdiGetDisplayStateNonIntrusive 不同，驱动程序的 DxgkDdiGetDisplayStateIntrusive 例程可以执行对用户产生明显副作用的更多侵入性操作。侵入性操作的定义如下 (非侵入性操作不具有以下任何属性) ：

它会导致副作用 (对用户 (可见的故障) ，例如暂时停止扫描和破坏监视器连接检查) 。
它速度缓慢，如果在第二) 中频繁调用 (多次，则会影响系统或显示性能。
它直接或间接更改显示子系统 (或任何其他子系统) 的状态。

在收集数据时，驱动程序不应有意更改系统的状态。

相对于对 DxgkDdiGetDisplayStateNonIntrusive 的调用，OS 调用此例程的频率要低得多。在大多数错误情况下，OS 将首先调用 DxgkDdiGetDisplayStateNonIntrusive ，然后调用 DxgkDdiGetDisplayStateIntrusive ，以确保侵入性调用的任何意外影响不会影响非侵入性数据收集。

DXGKRNL 将调用此例程，并将 NumOfTargets 设置为 OS 报告有一个监视器连接并填充了相应的 VidPnTargetId 的目标数。当驱动程序认为给定目标上没有连接监视器时，它应为该目标设置 ReturnSubStatus 以DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED。

注意

如果驱动程序在收集信息时在给定 vidpntarget 上遇到故障，则它应使用 ReturnSubStatus 设置错误状态并转到下一个 vidpntarget，除非所有路径都失败，否则不会使整个调用失败。理想情况下，驱动程序应在一些内部错误日志中记录此调用期间遇到的错误，以便当 OS 调用 DxgkDdiCollectDiagnosticInfo 来收集黑盒信息时，这些错误会作为内部日志收集的一部分捕获，以帮助 IHV 调试。

OS 将有足够的超时 (大约 5 秒) DxgkDdiGetDisplayStateIntrusive 完成，这为驱动程序提供了更多时间来收集所有相关状态。超时后，如果驱动程序在此调用中挂起，OS 可能会错误地检查计算机并收集转储，因此微型端口应尝试始终在时间范围内完成此调用。

此 DDI 的同步级别为零级同步。