poFxRegisterDevice 函式 (wdm.h)

發行項
03/01/2024

PoFxRegisterDevice 例程會向電源管理架構註冊裝置， (PoFx) 。

語法

NTSTATUS PoFxRegisterDevice(
  [in]  PDEVICE_OBJECT Pdo,
  [in]  PPO_FX_DEVICE  Device,
  [out] POHANDLE       *Handle
);

參數

[in] Pdo

實體裝置物件的指標， (PDO) 。此參數指向代表所註冊實體裝置的 DEVICE_OBJECT 結構。呼叫端是裝置的電源原則擁有者，通常是裝置的函式驅動程式。

[in] Device

呼叫端配置的 PO_FX_DEVICE 結構的指標，其中包含裝置的註冊資訊。此結構包含設備驅動器所實作之一組回呼例程的指標。 PoFx 會呼叫這些例程來與驅動程序通訊。

[out] Handle

例程寫入句柄的位置指標，代表使用PoFx註冊裝置的句柄。設備驅動器會將此句柄當做輸入參數傳遞給它所呼叫的其他 PoFxXxx 例程。驅動程式必須先呼叫 PoFxRegisterDevice ，才能在驅動程式呼叫任何其他 PoFxXxx 例程以電源管理裝置之前註冊裝置。

傳回值

如果例程成功註冊裝置，PoFxRegisterDevice 會傳回STATUS_SUCCESS。可能的錯誤傳回值包括下列狀態代碼。

傳回碼	Description
STATUS_INVALID_PARAMETER	Pdo 為 NULL;或 PPO_FX_DEVICE 結構的版本號碼無效或元件計數為零;或為元件指定的閑置狀態數目為零;或閑置狀態的描述無效。
STATUS_DEVICE_NOT_READY	裝置未就緒。
STATUS_INSUFFICIENT_RESOURCES	資源不足，無法完成註冊。

備註

設備驅動器通常會從驅動程式的IRP_MN_START_DEVICE 要求處理程式呼叫此例程。驅動程式在裝置收到 IRP_MN_START_DEVICE 要求之前，不得呼叫此例程。當裝置第一次啟動時，裝置會收到第一個 IRP_MN_START_DEVICE 要求。裝置在停止資源平衡之後，每次重新啟動裝置時，都會收到額外的 IRP_MN_START_DEVICE 要求。註冊已註冊裝置的 PoFxRegisterDevice 呼叫是嚴重錯誤，並導致錯誤檢查。請注意，PoFx 會將裝置結構的深層複本複製到其記憶體中。

在驅動程式呼叫 PoFxRegisterDevice 之前，裝置必須符合下列條件：

裝置 (亦即 PDO) 尚未向 PoFx 註冊。
裝置處於 D0 (完全處於電源狀態) 。
裝置處於執行中狀態。
裝置中的每個元件都位於 F0 (完全處於電源狀態) 。
每個元件都在使用中條件中。

藉由向PoFx註冊裝置，驅動程式會負責在主動使用元件以及元件閑置時通知PoFx。註冊裝置時，驅動程式必須呼叫 PoFxActivateComponent 例程以取得元件硬體緩存器的存取權，而且驅動程序必須呼叫 PoFxIdleComponent 例程，以在驅動程式不再需要存取元件時通知PoFx。

在驅動程式呼叫 PoFxRegisterDevice 以向 PoFx 註冊裝置之後，裝置中的所有元件都會完全開啟且處於作用中狀況，讓驅動程式可以完成硬體初始化。若要開始主動式電源管理，驅動程式必須呼叫 PoFxStartDevicePowerManagement 例程。

根據預設， PoFxStartDevicePowerManagement 會將所有元件切換至閑置條件。如果驅動程式要求元件在電源管理啟動后立即處於作用中條件，驅動程式必須藉由呼叫 PoFxActivateComponent 例程明確地啟動元件，而且此呼叫必須在 PoFxRegisterDevice 呼叫之後，但在 PoFxStartDevicePowerManagement 呼叫之前發生。

一般而言，單一元件裝置的 Kernel-Mode Driver Framework (KMDF) 驅動程式不會呼叫 PoFxRegisterDevice 向 PoFx 註冊裝置。相反地，當 KMDF 呼叫驅動程式的 EvtDeviceWdmPostPoFxRegisterDeviceDevice 回呼函式時，此驅動程式會收到 PoFx 註冊句柄。如需詳細資訊，請參閱支援 Single-Component 裝置的多個功能電源狀態。

如需多元件裝置 KMDF 驅動程式如何向 PoFx 註冊的資訊，請參閱支援 Multiple-Component 裝置的多重功能電源狀態。

規格需求

需求	值
最低支援的用戶端	從 Windows 8 開始提供。
目標平台	Universal
標頭	wdm.h
程式庫	Ntoskrnl.lib
Dll	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL