poRegisterPowerSettingCallback 函式 (wdm.h)

PoRegisterPowerSettingCallback 例程會註冊電源設定回呼例程，以接收指定電源設定中變更的通知。

語法

NTSTATUS PoRegisterPowerSettingCallback(
  [in, optional] PDEVICE_OBJECT          DeviceObject,
  [in]           LPCGUID                 SettingGuid,
  [in]           PPOWER_SETTING_CALLBACK Callback,
  [in, optional] PVOID                   Context,
  [out]          PVOID                   *Handle
);

參數

[in, optional] DeviceObject

與這個例程呼叫端相關聯的 DEVICE_OBJECT 結構的指標。 這是選擇性參數。 它只會在內部用於偵錯。 如果未提供此參數，它必須設定為 NULL。

[in] SettingGuid

GUID 的指標，表示此註冊的電源設定。 當指定的電源設定變更時，電源管理員會呼叫回呼例程來通知驅動程序變更，並提供設定的新值。 如需詳細資訊，請參閱＜備註＞。

[in] Callback

呼叫端實作電源設定回呼例程的指標，Power Manager 會在指定的電源設定變更時呼叫。 如需回呼例程的功能原型，請參閱 Power-Setting Callback。

[in, optional] Context

回呼例程之內容的指標。 這是選擇性參數。 它會提供，以便將驅動程式或裝置內容傳遞至回呼例程。 如果未使用此參數，則必須將它設定為 NULL。

[out] Handle

Power Manager 用來表示回呼例程的句柄。 驅動程式必須在 呼叫 PoUnregisterPowerSettingCallback 中提供此句柄，以取消註冊回呼例程。

傳回值

PoRegisterPowerSettingCallback 會傳回下列其中一項：

備註

驅動程式會呼叫 PoRegisterPowerSettingCallback ，向電源管理員註冊回呼例程。 電源管理員接著會呼叫此回呼例程，以在變更指定的電源設定之後通知驅動程式。 此外，電源管理員會立即呼叫回呼例程並傳遞電源設定的目前值，來初始化驅動程式的電源設定。 不論電源設定是否已實際變更，電源管理員都會以這種方式初始化驅動程式的電源設定。

驅動程式應該針對驅動程式需要監視的每個電源設定呼叫 PoRegisterPowerSettingCallback 。 驅動程式應該在初始化期間在其 DriverEntry 例程中呼叫此例程。 一般而言，大部分驅動程式都會在 Context 參數中傳遞裝置延伸模組的指標。

若要取消註冊電源設定回呼，請呼叫 PoUnregisterPowerSettingCallback 例程。

一般而言，Kernel-Mode Driver Framework (KMDF) 驅動程式應該從其 EvtDeviceSelfManagedIoInit 回呼函式呼叫 PoRegisterPowerSettingCallback，而且應該從其 EvtDeviceSelfManagedIoCleanup 回呼函式呼叫 PoUnregisterPowerSettingCallback。 這些驅動程式不應該從其 EvtDriverDeviceAdd 回呼函式呼叫 PoRegisterPowerSettingCallback;否則，在完全建置驅動程式堆疊之前，可能會呼叫電源設定回呼例程。

當電源狀態中的轉換變更設定的值，或當電源管理員變更設定的值時，就會呼叫針對特定電源設定註冊的回呼例程。 例如，如果 SettingGuid 指向 GUID 值GUID_LIDSWITCH_STATE_CHANGE，則會在膝上型電腦按兩下開啟或關閉時呼叫回呼例程。 在此範例中傳遞至回呼例程的 Value 參數指向 ULONG 值，如果 lid 參數的狀態從關閉變更為開啟，則為 0;如果 lid 參數的狀態從開啟變更為關閉，則為 0。 如需詳細資訊，請參閱 Wdm.h 頭檔中的電源設定 GUID 定義和廣泛的批注。

在登錄例程傳回的 PoRegisterPowerSettingCallback 呼叫之前，可能會立即發生回呼例程的初始呼叫。

PoRegisterPowerSettingCallback 只能在 IRQL = PASSIVE_LEVEL呼叫。

Power-Setting 回呼

電源設定回呼例程的函式原型如下所示：

NTSTATUS
POWER_SETTING_CALLBACK (
  _In_ LPCGUID SettingGuid,
  _In_ PVOID Value,
  _In_ ULONG ValueLength,
  _Inout_opt_ PVOID Context
);

電源設定回呼參數如下：

SettingGuid
GUID 的指標，表示已變更的電源設定。 電源設定及其對應的 GUID 定義於 Wdm.h 中。

值
變更之電源設定之新值的指標。

ValueLength
ULONG 類型的值，指定新電源設定值的大小，以位元組為單位。

內容
驅動程式在呼叫已註冊回呼例程的 PoRegisterPowerSettingCallback 中所提供之內容的指標。

電源管理員會在 IRQL = PASSIVE_LEVEL呼叫電源設定回呼。

範例

若要定義電源設定回呼例程，您必須先提供函式宣告，以識別您要定義的回呼函式類型。 Windows 提供一組驅動程式的回呼函式類型。 使用回呼函式類型宣告函式有助於 驅動程式的程式代碼分析、 靜態驅動程式驗證器 (SDV) ，以及其他驗證工具尋找錯誤，而且這是撰寫 Windows 操作系統驅動程式的需求。

例如，若要定義名為 MyPowerSettingCallback的電源設定回呼例程，請使用POWER_SETTING_CALLBACK類型，如下列程式代碼範例所示：

POWER_SETTING_CALLBACK MyPowerSettingCallback;

然後，實作回呼例程，如下所示：

_Use_decl_annotations_
NTSTATUS
  MyPowerSettingCallback(
    LPCGUID SettingGuid,
    PVOID Value,
    ULONG ValueLength,
    PVOID Context 
    )
  {
      // Function body
  }

POWER_SETTING_CALLBACK函式類型定義於 Wdm.h 頭檔中。 若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將 _Use_decl_annotations_ 批註新增至函式定義。 註釋 _Use_decl_annotations_ 可確保使用頭檔中套用至POWER_SETTING_CALLBACK函式類型的註釋。 如需函數宣告需求的詳細資訊，請參閱 使用WDM驅動程式的函式角色類型來宣告函式。 如需 的相關信息 _Use_decl_annotations_，請參閱 標註函式行為。

規格需求

另請參閱

DriverEntry

EvtDeviceSelfManagedIoCleanup

EvtDeviceSelfManagedIoInit

EvtDriverDeviceAdd

PoUnregisterPowerSettingCallback