EVT_WDF_DEVICE_PREPARE_HARDWARE回呼函式 (wdfdevice.h)

[適用於 KMDF 和 UMDF]

驅動程式的 EvtDevicePrepareHardware 事件回呼函式會執行讓驅動程式存取裝置所需的任何作業。

語法

EVT_WDF_DEVICE_PREPARE_HARDWARE EvtWdfDevicePrepareHardware;

NTSTATUS EvtWdfDevicePrepareHardware(
  [in] WDFDEVICE Device,
  [in] WDFCMRESLIST ResourcesRaw,
  [in] WDFCMRESLIST ResourcesTranslated
)
{...}

參數

[in] Device

架構裝置物件的句柄。

[in] ResourcesRaw

架構資源清單物件的句柄，可識別 隨插即用 管理員指派給裝置的原始硬體資源。

[in] ResourcesTranslated

架構資源清單物件的句柄，識別 隨插即用 管理員指派給裝置的已轉譯硬體資源。

傳回值

如果 EvtDevicePrepareHardware 回呼函式沒有發生任何錯誤，它必須傳回STATUS_SUCCESS或另一個狀態值，NT_SUCCESS (狀態) 等於 TRUE。 否則，它必須傳回狀態值，NT_SUCCESS (狀態) 等於 FALSE。 請勿傳回STATUS_NOT_SUPPORTED。

如果NT_SUCCESS (状态) 等於 FALSE，架構會呼叫驅動程式的 EvtDeviceReleaseHardware 回呼函式。

如需此回呼函式傳回值的詳細資訊，請參閱 報告裝置失敗。

備註

若要註冊 EvtDevicePrepareHardware 回呼函式，驅動程式必須呼叫 WdfDeviceInitSetPnpPowerEventCallbacks。

如果驅動程式已註冊裝置的 EvtDevicePrepareHardware 回呼函式，架構會在 隨插即用 管理員將硬體資源指派給裝置之後，以及在裝置進入未初始化的 D0 狀態之後呼叫函式。 (隨插即用 管理員一律會在啟動該裝置的子裝置之前啟動父裝置。)

架構會先呼叫驅動程式的 EvtDevicePrepareHardware 回呼函式，再呼叫驅動程式的 EvtDeviceD0Entry 回呼函式。

EvtDevicePrepareHardware 回呼函式會使用其收到的 ResourcesRaw 和 ResourcesTranslated 句柄來存取裝置的原始和翻譯硬體資源。 回呼函式可以呼叫 WdfCmResourceListGetCount 和 WdfCmResourceListGetDescriptor 來周遊資源清單。 此回呼函式無法修改資源清單。

如需資源清單和資源出現順序的詳細資訊，請參閱 原始和翻譯的硬體資源。

一般而言，驅動程式的 EvtDevicePrepareHardware 回呼函式會視需要執行下列動作：

• 將實體記憶體位址對應至虛擬位址，讓驅動程式可以存取指派給裝置的記憶體
• 決定裝置的修訂編號
• 設定USB裝置
• 從其他驅動程式取得驅動程式定義的介面

或者，驅動程式的 EvtDevicePrepareHardware 回呼函式可能會將工作專案排入佇列，以完成任何其他需要大量時間的設定工作。 針對這類作業使用工作專案有助於確保裝置的啟動時間不會增加系統開機時間。 如需詳細資訊，請參閱 使用 Framework 工作專案。

一般而言，所有其他硬體初始化作業，包括載入韌體，都應該在裝置進入其工作 (D0) 狀態時發生，因此應該在驅動程式的 EvtDeviceD0Entry 回呼函式中執行。

ResourcesRaw 和 ResourcesTranslated 處理 EvtDevicePrepareHardware 回呼函式接收的有效狀態，直到驅動程式的 EvtDeviceReleaseHardware 回呼函式傳回為止。

如需硬體資源的詳細資訊，請參閱 Framework-Based 驅動程式的硬體資源。

如需架構何時呼叫此回呼函式的詳細資訊，請參閱 PnP 和電源管理案例。

如需提供此回呼函式的驅動程式詳細資訊，請參閱 支援函式驅動程式中的 PnP 和電源管理。

規格需求

需求	值
目標平台	Universal
最小 KMDF 版本	1.0
最低UMDF版本	2.0
標頭	wdfdevice.h (包含 Wdf.h)
IRQL	PASSIVE_LEVEL

另請參閱

EvtDeviceReleaseHardware