IoSetCompletionRoutineEx 함수(wdm.h)

아티클
02/29/2024

IoSetCompletionRoutineEx 루틴은 다음 하위 수준 드라이버가 지정된 IRP에 대해 요청된 작업을 완료할 때 호출되는 IoCompletion 루틴을 등록합니다.

구문

NTSTATUS IoSetCompletionRoutineEx(
  [in]           PDEVICE_OBJECT         DeviceObject,
  [in]           PIRP                   Irp,
  [in]           PIO_COMPLETION_ROUTINE CompletionRoutine,
  [in, optional] PVOID                  Context,
  [in]           BOOLEAN                InvokeOnSuccess,
  [in]           BOOLEAN                InvokeOnError,
  [in]           BOOLEAN                InvokeOnCancel
);

매개 변수

[in] DeviceObject

드라이버의 디바이스 개체에 대한 포인터입니다.

[in] Irp

드라이버가 처리 중인 IRP 에 대한 포인터입니다.

[in] CompletionRoutine

다음 하위 드라이버가 패킷을 완료할 때 호출되는 드라이버 제공 IoCompletion 루틴의 진입점을 지정합니다.

[in, optional] Context

IoCompletion 루틴에 전달할 드라이버 결정 컨텍스트에 대한 포인터입니다. IoCompletion 루틴은 IRQL <= DISPATCH_LEVEL 호출되므로 컨텍스트 정보는 페이지가 없는 메모리에 저장되어야 합니다.

[in] InvokeOnSuccess

NT_SUCCESS 매크로의 결과에 따라 IRP가 IRP의 IO_STATUS_BLOCK 구조에서 성공 상태 값으로 완료될 경우 완료 루틴이 호출되는지 여부를 지정합니다(NTSTATUS 값 사용 참조).

[in] InvokeOnError

IRP의 IO_STATUS_BLOCK 구조에서 비uccess 상태 값으로 IRP가 완료될 경우 완료 루틴이 호출되는지 여부를 지정합니다.

[in] InvokeOnCancel

드라이버 또는 커널이 IRP를 취소하기 위해 IoCancelIrp 을 호출한 경우 완료 루틴이 호출되는지 여부를 지정합니다.

반환 값

이 루틴은 성공 시 STATUS_SUCCESS 반환하거나 작업에 메모리가 부족한 경우 STATUS_INSUFFICIENT_RESOURCES.

설명

IoSetCompletionRoutine과 달리 IoSetCompletionRoutineEx 루틴은 NTSTATUS 값을 반환합니다. 드라이버는 이 값을 검사 IoCompletion 루틴이 성공적으로 등록되었는지 확인해야 합니다. IoCompletion 루틴이 성공적으로 등록되면 IoSetCompletionRoutineEx는 IoCompletion 루틴이 실행될 때까지 할당된 상태로 유지되는 메모리를 할당합니다. 드라이버는 IoCallDriver를 호출하여 IoCompletion 루틴이 실행되도록 해야 합니다. 그렇지 않으면 커널이 메모리를 누수합니다.

IoCompletion 루틴은 DeviceObject가 가리키는 디바이스 개체를 소유하는 드라이버에 속해야 합니다. 이 요구 사항은 IoCompletion 루틴이 반환되기 전에 언로드되지 않도록 방지합니다.

IoSetCompletionRoutineEx의 동작은 다음을 제외하고 IoSetCompletionRoutine 루틴과 동일합니다.

IoSetCompletionRoutineEx는 IoCompletion 루틴이 실행되기 전에 플러그 앤 플레이 없는 드라이버가 언로드되지 않도록 보장합니다.
IoSetCompletionRoutineEx 는 NTSTATUS 값을 반환하는 루틴입니다.

요구 사항

요구 사항	값
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI 규정 준수 규칙	CompleteRequest(wdm), CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), HwStorPortProhibitedDPi(storport), IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildFsdForward(wdm), wdm).IoBuildFsdIrpSignalEventInCompletion(wdm), IoBuildFsdIrpSignalEventInCompletion2(wdm), IoBuildFsdIrpSignalEventInCompletion3(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoSetCompletionExCompleteIrp(wdm), IoSetCompletionRoutineExCheck(wdm), IoSetCompletionRoutineExCheckDeviceObject(wdm), LowerDriverReturn(wdm), MarkPowerDown(wdm ) , MarkQueryRelations(wdm), MarkStartDevice(wdm), PendedCompletedRequestEx(wdm), SetCompletionRoutineFromDispatch(kmdf), SignalEventInCompletion(wdm), SignalEventInCompletion2(wdm), SignalEventInCompletion3(wdm), StartDeviceWait2(wdm), StartDeviceWait4(wdm)