DXGKDDI_GETDISPLAYSTATEINTRUSIVE回呼函式 (dispmprt.h)

發行項
02/23/2024

操作系統 (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 設定為作業系統報告已連線且已填入對應 VidPnTargetId 的監視器數目。當驅動程式認為指定的目標上沒有連線的監視器時，它應該將該目標的 ReturnSubStatus 設定為DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED。

注意

如果在收集資訊時，驅動程式在指定的 vidpntarget 上遇到失敗，它應該使用 ReturnSubStatus 來設定錯誤狀態，並繼續進行下一個 vidpntarget，而且除非所有路徑叫用失敗，否則不會讓整體呼叫失敗。驅動程式應該在一些內部錯誤記錄檔中記錄此呼叫期間發生的錯誤，以便在OS呼叫 DxgkDdiCollectDiagnosticInfo 以收集黑箱資訊時，這些錯誤會擷取為內部記錄收集的一部分，以協助 IHV 偵錯。

OS 將有足夠的逾時 (大約 5 秒) ，讓 DxgkDdiGetDisplayStateIntrusive 完成，讓驅動程式有更多時間收集所有相關狀態。逾時之後，OS 可能會錯誤檢查計算機，並在驅動程式在此呼叫中停止回應時收集傾印，因此迷你埠應該嘗試在時間範圍內一律完成此呼叫。

此 DDI 的同步處理層級為零層級同步處理。