PoRegisterPowerSettingCallback 함수(ntifs.h)

아티클
07/11/2023

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

지정된 전원 설정이 변경될 때 전원 관리자가 호출하는 호출자 구현 전원 설정 콜백 루틴에 대한 포인터입니다. 콜백 루틴에 대한 기능 프로토타입은 아래 의 전원 설정 콜백을 참조하세요.

[in, optional] Context

콜백 루틴의 컨텍스트에 대한 포인터입니다. 이 매개 변수는 선택적 요소입니다. 드라이버 또는 디바이스 컨텍스트를 콜백 루틴에 전달할 수 있도록 제공됩니다. 이 매개 변수를 사용하지 않는 경우 NULL로 설정해야 합니다.

[out] Handle

전원 관리자가 콜백 루틴을 나타내는 데 사용하는 핸들입니다. 이후에 드라이버는 PoUnregisterPowerSettingCallback 호출에서 이 핸들을 제공하여 콜백 루틴의 등록을 취소해야 합니다.

반환 값

PoRegisterPowerSettingCallback 은 다음 중 하나를 반환합니다.

반환 코드	설명
STATUS_SUCCESS	루틴이 콜백 루틴을 등록했습니다.
STATUS_ INSUFFICIENT_RESOURCES	루틴에서 콜백 루틴을 등록하는 데 필요한 시스템 리소스를 할당할 수 없습니다.

설명

드라이버는 PoRegisterPowerSettingCallback을 호출하여 전원 관리자에 콜백 루틴을 등록합니다. 이후에 전원 관리자는 지정된 전원 설정이 변경된 후 드라이버에 알리기 위해 이 콜백 루틴을 호출합니다. 또한 전원 관리자는 즉시 콜백 루틴을 호출하고 전원 설정의 현재 값을 전달하여 드라이버의 전원 설정을 초기화합니다. 전원 관리자는 전원 설정이 실제로 변경되었는지 여부에 관계없이 이러한 방식으로 드라이버의 전원 설정을 초기화합니다.

드라이버는 드라이버가 모니터링해야 하는 각 전원 설정에 대해 PoRegisterPowerSettingCallback 을 호출해야 합니다. 드라이버는 초기화 중에 DriverEntry 루틴에서 이 루틴을 호출해야 합니다. 일반적으로 대부분의 드라이버는 Context 매개 변수의 디바이스 확장에 대한 포인터를 전달합니다.

전원 설정 콜백의 등록을 취소하려면 PoUnregisterPowerSettingCallback 루틴을 호출합니다.

일반적으로 Kernel-Mode 드라이버 프레임워크(KMDF) 드라이버는 EvtDeviceSelfManagedIoInit 콜백 함수에서 PoRegisterPowerSettingCallback을 호출해야 하며, EvtDeviceSelfManagedIoCleanup 콜백 함수에서 PoUnregisterPowerSettingCallback을 호출해야 합니다. 이러한 드라이버는 EvtDriverDeviceAdd 콜백 함수에서 PoRegisterPowerSettingCallback을 호출해서는 안 됩니다. 그렇지 않으면 드라이버 스택이 완전히 빌드되기 전에 전원 설정 콜백 루틴이 호출될 수 있습니다.

특정 전원 설정에 대해 등록된 콜백 루틴은 전원 상태 전환이 발생하여 설정 값을 변경하거나 전원 관리자가 설정 값을 변경할 때 호출됩니다. 예를 들어 SettingGuid 가 GUID_LIDSWITCH_STATE_CHANGE GUID 값을 가리키는 경우 랩톱 컴퓨터의 덮개를 열거나 닫을 때 콜백 루틴이 호출됩니다. 이 예제의 콜백 루틴에 전달된 Value 매개 변수는 덮개 스위치의 상태가 닫힘에서 열기로 변경된 경우 1이고 덮개 스위치의 상태가 열기에서 닫힘으로 변경된 경우 0인 ULONG 값을 가리킵니다. 자세한 내용은 Wdm.h 헤더 파일의 전원 설정 GUID 정의 및 광범위한 주석을 참조하세요.

콜백 루틴에 대한 초기 호출은 루틴을 등록 하는 PoRegisterPowerSettingCallback 호출이 반환되기 직전에 발생할 수 있습니다.

PoRegisterPowerSettingCallback 은 IRQL = PASSIVE_LEVEL 호출할 수 있습니다.

Power-Setting 콜백

전원 설정 콜백 루틴 및 해당 매개 변수의 함수 프로토타입은 다음과 같습니다. 전원 관리자는 IRQL = PASSIVE_LEVEL 전원 설정 콜백을 호출합니다.

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

매개 변수	Description
SettingGuid	변경된 전원 설정을 나타내는 GUID에 대한 포인터입니다. 전원 설정 및 해당 GUID는 Wdm.h에 정의되어 있습니다.
값	변경된 전원 설정의 새 값에 대한 포인터입니다.
ValueLength	새 전원 설정 값의 크기(바이트)를 지정하는 ULONG 형식의 값입니다.
컨텍스트	콜백 루틴을 등록한 PoRegisterPowerSettingCallback 호출에서 드라이버가 제공한 컨텍스트에 대한 포인터입니다.

예제

전원 설정 콜백 루틴을 정의하려면 먼저 정의할 콜백 함수의 형식을 식별하는 함수 선언을 제공해야 합니다. 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 대한 자세한 내용은 함수 동작 주석 지정을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista
대상 플랫폼	유니버설
헤더	ntifs.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL(설명 섹션 참조)