ExRegisterCallback 함수(wdm.h)

아티클
02/27/2024

ExRegisterCallback 루틴은 지정된 콜백 개체에 지정된 콜백 루틴을 등록합니다.

구문

PVOID ExRegisterCallback(
  [in, out]      PCALLBACK_OBJECT   CallbackObject,
  [in]           PCALLBACK_FUNCTION CallbackFunction,
  [in, optional] PVOID              CallbackContext
);

매개 변수

[in, out] CallbackObject

ExCreateCallback 루틴에서 가져온 콜백 개체에 대한 포인터입니다.

[in] CallbackFunction

드라이버 구현 콜백 루틴에 대한 포인터로, 비페이지할 수 있어야 합니다. 콜백 루틴은 다음 프로토타입을 준수해야 합니다.

VOID
(*PCALLBACK_FUNCTION ) (
    IN PVOID CallbackContext,
    IN PVOID Argument1,
    IN PVOID Argument2
    );

콜백 루틴 매개 변수는 다음과 같습니다.

CallbackContext

ExRegisterCallback의 CallbackContext 매개 변수에 지정된 드라이버 제공 컨텍스트 영역에 대한 포인터입니다.

Argument1

콜백 개체에서 정의한 매개 변수에 대한 포인터입니다.

Argument2

콜백 개체에서 정의한 매개 변수에 대한 포인터입니다.

[in, optional] CallbackContext

호출될 때마다 콜백 루틴의 컨텍스트 매개 변수로 전달될 데이터 항목의 호출자 정의 구조에 대한 포인터입니다. 일반적으로 컨텍스트는 호출자의 디바이스 개체 확장의 일부입니다.

반환 값

ExRegisterCallback 은 불투명으로 처리되고 시스템 사용을 위해 예약되어야 하는 콜백 등록 핸들에 대한 포인터를 반환합니다. ExRegisterCallback이 오류와 함께 완료된 경우 이 포인터는 NULL입니다.

설명

드라이버는 ExRegisterCallback 을 호출하여 지정된 콜백 개체에 콜백 루틴을 등록합니다.

개체가 등록된 콜백 루틴을 하나만 허용하고 이러한 루틴이 이미 등록된 경우 ExRegisterCallback 은 NULL을 반환합니다.

ExRegisterCallback 호출자는 ExUnregisterCallback 호출에서 나중에 사용할 반환된 포인터를 저장해야 합니다. 콜백 개체에 대해 등록된 콜백 루틴 목록에서 콜백 루틴을 제거할 때 포인터가 필요합니다.

등록된 콜백 루틴의 Argument1 및 Argument2 의 의미는 콜백 개체에 따라 달라지고 이를 만든 구성 요소에 의해 정의됩니다. 다음은 시스템 정의 콜백 개체에 대한 매개 변수입니다.

\Callback\SetSystemTime

Argument1 (SetSystemTime)

사용되지 않습니다.

Argument2 (SetSystemTime)

사용되지 않습니다.

\Callback\PowerState**

Argument1 (PowerState)

PVOID 형식으로 캐스팅되는 PO_CB_XXX 상수 값입니다.
PO_CB_AC_STATUS — 시스템이 A/C에서 배터리 전원으로 변경되었거나 그 반대로 변경되었음을 나타냅니다.
PO_CB_LID_SWITCH_STATE — 덮개 스위치가 상태를 변경했음을 나타냅니다.
PO_CB_PROCESSOR_POWER_POLICY — 시스템 프로세서 전원 정책이 변경되었음을 나타냅니다.
PO_CB_SYSTEM_POWER_POLICY — 시스템 전원 정책이 변경되었음을 나타냅니다.
PO_CB_SYSTEM_STATE_LOCK — 시스템 전원 상태 변경이 임박했음을 나타냅니다. 페이징 경로의 드라이버는 이러한 변경에 대한 조기 경고를 수신하기 위해 이 콜백에 등록할 수 있으므로 전원 상태가 변경되기 전에 메모리에 코드를 잠글 수 있습니다.

Argument2 (PowerState)

PVOID 형식으로 캐스팅되는 TRUE 또는 FALSE 값입니다.

Argument1이 PO_CB_AC_STATUS 경우 컴퓨터가 현재 A/C 전원 공급 장치를 사용하는 경우 Argument2는 TRUE이고 컴퓨터가 배터리 전원으로 실행 중인 경우 FALSE입니다.
Argument1이 PO_CB_LID_SWITCH_STATE 경우 뚜껑이 현재 열려 있으면 Argument2가 TRUE이고 덮개를 닫으면 FALSE입니다.
Argument1이 PO_CB_PROCESSOR_POWER_POLICY 경우 Argument2는 사용되지 않습니다.
Argument1이 PO_CB_SYSTEM_POWER_POLICY 경우 Argument2는 사용되지 않습니다.
Argument1이 PO_CB_SYSTEM_STATE_LOCK 경우 컴퓨터가 시스템 전원 상태 S0을 종료하려고 하면 Argument2가 FALSE이고 컴퓨터에서 S0을 다시 입력한 경우 TRUE입니다.

\Callback\Processor추가

Argument1 (ProcessorAdd)

프로세서 변경 알림 이벤트를 설명하는 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 구조체에 대한 포인터입니다. 이 포인터는 PVOID 형식으로 캐스팅됩니다. 콜백 루틴은 이 구조체의 내용을 수정해서는 안 됩니다.

Argument2 (ProcessorAdd)

NTSTATUS 값이 포함된 변수에 대한 포인터입니다. 이 포인터는 PVOID 형식으로 캐스팅됩니다. 특정 조건에서 콜백 루틴은 이 변수에 오류 상태 값을 작성하여 새 프로세서를 추가하지 않아야 하는 이유를 나타낼 수 있습니다. 다음 세 가지 조건이 모두 충족되지 않는 한 디바이스 드라이버는 이 변수의 값을 변경해서는 안됩니다.

새 프로세서가 추가되지 않도록 하는 콜백 루틴을 처리하는 동안 오류가 발생합니다.
Argument1이 가리키는 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 구조체의 State 멤버 값은 KeProcessorAddStartNotify입니다.
Argument2가 가리키는 NSTATUS 변수에는 STATUS_SUCCESS 값이 포함됩니다. 즉, 콜백 루틴은 이전에 다른 콜백 알림 클라이언트에서 작성한 오류 상태 값을 덮어쓰지 않아야 합니다.

Windows Vista부터 \Callback\ProcessorAdd 콜백 개체를 사용하여 프로세서 모집단의 변경 내용을 동적으로 추적할 수 있습니다. KeRegisterProcessorChangeCallback 루틴은 유사한 정보를 제공하지만 드라이버가 초기 다중 프로세서 시스템 구성에서 프로세서를 열거하는 데 사용할 수 있는 KE_PROCESSOR_CHANGE_ADD_EXISTING 플래그를 추가로 지원합니다. Windows Server 2008 이상 버전의 Windows에서 실행되는 드라이버의 경우 가능한 경우 \Callback\ProcessorAdd 콜백 개체 대신 KeRegisterProcessorChangeCallback을 사용합니다.

콜백 개체에 대한 자세한 내용은 콜백 개체를 참조하세요.

운영 체제는 ExNotifyCallback 루틴이라는 콜백을 만든 드라이버가 있는 동일한 IRQL에서 등록된 콜백 루틴을 호출합니다.

요구 사항

요구 사항	값
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm)