FltCancellableWaitForMultipleObjects 함수(fltkernel.h)

아티클
02/29/2024

FltCancellableWaitForMultipleObjects는 하나 이상의 디스패처 개체에서 취소 가능한 대기 작업(종료될 수 있는 대기)을 실행합니다.

구문

NTSTATUS FLTAPI FltCancellableWaitForMultipleObjects(
  [in]           ULONG              Count,
  [in]           PVOID []           ObjectArray,
  [in]           WAIT_TYPE          WaitType,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PKWAIT_BLOCK       WaitBlockArray,
  [in]           PFLT_CALLBACK_DATA CallbackData
);

매개 변수

[in] Count

대기할 개체의 수입니다.

[in] ObjectArray

호출자가 스토리지를 제공하는 디스패처 개체(이벤트, 뮤텍스, 세마포, 스레드 및 타이머)에 대한 포인터 배열에 대한 포인터입니다.

[in] WaitType

WaitAll 값이 있는 열거형으로, 대기가 충족되기 전에 지정된 모든 개체가 신호 상태를 달성해야 했음을 나타냅니다. 또는 WaitAny - 대기가 충족되기 전에 개체 중 하나가 신호 상태를 달성해야 했음을 나타냅니다.

[in, optional] Timeout

선택적 제한 시간 값에 대한 포인터입니다. 이 매개 변수는 대기가 완료될 100나노초 단위의 절대 또는 상대 시간을 지정합니다.

Timeout이 0 값(즉, *Timeout == 0)을 가리키면 루틴은 기다리지 않고 반환됩니다. 호출자가 NULL 포인터(즉, Timeout == NULL)를 제공하는 경우 루틴은 모든 디스패처 개체가 신호된 상태로 설정될 때까지 무기한 대기합니다.

양수 값은 1601년 1월 1일을 기준으로 절대 시간을 지정합니다. 음수 값은 현재 시간을 기준으로 간격을 지정합니다. 절대 만료 시간은 시스템 시간의 변경 내용을 추적합니다. 상대 만료 시간은 시스템 시간 변경의 영향을 받지 않습니다.

시간 제한을 지정하면 지정된 간격이 만료될 때 지정된 대기 조건이 충족되지 않으면 대기가 자동으로 충족됩니다.

0의 제한 시간 값(즉, *Timeout == 0)을 사용하면 대기 조건 집합을 테스트하고 뮤텍스 획득과 같이 대기가 즉시 충족될 수 있는 경우 조건부로 추가 작업을 수행할 수 있습니다.

[in, optional] WaitBlockArray

Count <= THREAD_WAIT_OBJECTS 경우 WaitBlockArray는 NULL일 수 있습니다. 그렇지 않으면 이 매개 변수는 바이트의 메모리 버퍼 sizeof(KWAIT_BLOCK) * Count 를 가리킵니다. 루틴은 대기 작업을 수행하는 동안 레코드 유지에 이 버퍼를 사용합니다.

[in] CallbackData

사용자가 발급하고 사용자가 취소할 수 있는 I/O 작업을 나타내는 FLT_CALLBACK_DATA 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 호출자는 I/O 작업이 이 루틴 기간 동안 유효하게 유지되고 I/O에 취소 루틴 집합이 없어야 합니다(예: FltSetCancelCompletion 함수가 I/O 작업에서 호출되지 않았어야 함). CallbackData는 하위 수준 드라이버에 전달할 수 없으므로 호출자가 보유해야 합니다.

반환 값

FltCancellableWaitForMultipleObjects는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_SUCCESS	WaitType 매개 변수에 대해 WaitAll을 지정한 호출자와 ObjectArray 배열의 모든 디스패처 개체가 신호 상태로 설정되었습니다.
STATUS_TIMEOUT	지정된 대기 조건 집합이 충족되기 전에 시간 초과가 발생했습니다. 지정된 대기 조건 집합을 즉시 충족할 수 없고 시간 제한이 0으로 설정된 경우에도 이 값을 반환할 수 있습니다.
STATUS_WAIT_63 통해 STATUS_WAIT_0	호출자가 WaitType에 대해 WaitAny를 지정하고 ObjectArray 배열의 디스패처 개체 중 하나가 신호 상태로 설정되었습니다. 반환 값의 하위 6비트 는 대기를 충족하는 개체의 인덱스(0부터 시작)를 인코딩합니다.
STATUS_ABANDONED_WAIT_63 통해 STATUS_ABANDONED_WAIT_0	호출자가 중단된 뮤텍스를 기다리려고 했습니다. 반환 값의 하위 6비트에서는 ObjectArray 배열에 있는 뮤텍스의 인덱스(0부터 시작)를 인코딩합니다.
STATUS_CANCELLED	I/O 작업에 대한 보류 중인 취소 요청으로 인해 대기가 중단되었습니다. 이 값은 IRP 기반 작업에 해당하는 CallbackData 가 FltCancellableWaitForMultipleObjects 에 전달되고 FltCancelIo와 같은 루틴에 의해 I/O가 취소된 경우에만 반환됩니다.
STATUS_THREAD_IS_TERMINATING	애플리케이션 또는 사용자가 스레드를 종료했기 때문에 대기가 중단되었습니다.

반환 값은 대기의 상태 나타냅니다.

NT_SUCCESS 매크로는 다른 모든 상태 값에 대해 STATUS_CANCELLED 및 STATUS_THREAD_IS_TERMINATING 상태 값에 대해 FALSE("failure") 및 TRUE("success")를 반환합니다.

설명

FltCancellableWaitForMultipleObjects는 디스패처 개체에서 취소 가능한 대기 작업을 실행합니다. 사용자 또는 애플리케이션이 스레드를 종료하거나 FltCancelIo와 같은 루틴에 의해 스레드와 연결된 I/O 작업이 취소된 경우 대기가 취소됩니다.

루틴은 I/O 완료/취소 지침을 지원하도록 설계되었습니다. 이러한 지침의 목표는 사용자가 애플리케이션을 신속하게 종료할 수 있도록 하는 것입니다. 따라서 애플리케이션은 I/O 및 현재 I/O 작업을 실행하는 스레드를 신속하게 종료할 수 있어야 합니다. 이 루틴은 대기를 쉽게 취소할 수 있는 방식으로 사용자 스레드가 I/O 완료, 디스패처 개체 또는 동기화 변수에 대한 커널에서 차단(즉, 대기)하는 방법을 제공합니다. 또한 이 루틴은 스레드가 사용자 또는 애플리케이션에 의해 종료되는 경우 스레드의 대기를 종료할 수 있도록 허용합니다.

예를 들어 리디렉터에서 사용자 모드 I/O를 처리하고 보조 요청이 완료되기를 동기적으로 기다리기 위해 하나 이상의 보조 I/O 작업을 만들어야 할 수 있습니다. 이 작업을 수행하는 한 가지 방법은 보조 I/O 작업의 완료 루틴에 의해 신호를 받는 이벤트를 설정한 다음 이벤트가 신호를 받을 때까지 기다리는 것입니다. 그런 다음 취소 가능한 대기 작업을 수행하기 위해 FltCancellableWaitForMultipleObjects 를 호출하여 보조 I/O 작업과 연결된 이벤트 및 원래 사용자 모드 I/O 작업을 전달합니다. 보류 중인 종료 이벤트가 발생하거나 원래 사용자 모드 I/O 작업이 취소된 경우 이벤트가 신호를 받을 때까지 스레드의 대기가 취소됩니다.

대기를 종료해도 호출자가 발급한 I/O 작업은 자동으로 취소되지 않으며 호출자가 별도로 처리해야 합니다.

각 스레드 개체에는 여러 개체를 동시에 대기하는 데 사용할 수 있는 대기 블록의 기본 제공 배열이 있습니다. 추가 대기 블록 스토리지를 할당하지 않고 나중에 할당을 취소할 필요가 없으므로 가능하면 대기 다중 작업에서 대기 블록의 기본 제공 배열을 사용해야 합니다. 그러나 동시에 대기해야 하는 개체 수가 기본 제공 대기 블록 수보다 큰 경우 WaitBlockArray 매개 변수를 사용하여 대기 작업에 사용할 대체 대기 블록 집합을 지정합니다. 드라이버는 WaitBlockArray에 대해 충분히 큰 메모리 버퍼만 할당하면 됩니다. 버퍼를 초기화할 필요가 없으며 드라이버는 이를 불투명 구조로 처리할 수 있습니다. 루틴이 반환되면 버퍼를 해제할 수 있습니다.

Count가 MAXIMUM_WAIT_OBJECTS보다 크거나 WaitBlockArray 가 NULL이고 Count가 THREAD_WAIT_OBJECTS보다 큰 경우 시스템에서 버그 검사 0xC: MAXIMUM_WAIT_OBJECTS_EXCEEDED.

FltCancellableWaitForMultipleObjects에 전달된 ObjectArray 매개 변수의 요소 중 하나 이상이 뮤텍스를 참조하는 경우 특별한 고려 사항이 적용됩니다. 대기 중인 디스패처 개체가 뮤텍스인 경우 APC 배달은 대기하는 동안 다른 모든 디스패처 개체와 동일합니다. 그러나 FltCancellableWaitForMultipleObjects 가 STATUS_SUCCESS 함께 반환되고 스레드가 실제로 뮤텍스를 보유하면 특수 커널 모드 APC만 전달됩니다. 커널 모드와 사용자 모드 모두 다른 모든 APC의 배달은 사용하지 않도록 설정됩니다. APC 배달에 대한 이 제한은 뮤텍스가 해제될 때까지 유지됩니다.

뮤텍스는 MINLONG 시간만 재귀적으로 획득할 수 있습니다. 이 제한을 초과하면 루틴에서 STATUS_MUTANT_LIMIT_EXCEEDED 예외가 발생합니다.

CallbackData 매개 변수가 유효한 필터 관리자 IRP를 나타내는 경우 IRQL PASSIVE_LEVEL FltCancellableWaitForMultipleObjects 루틴을 호출해야 합니다. 그렇지 않으면 IRQL에서 APC_LEVEL 또는 같음으로 루틴을 호출할 수 있습니다. 필요한 경우 KeEnterCriticalRegion 또는 FsRtlEnterFileSystem 루틴을 호출하여 호출자가 일반 커널 APC를 사용하지 않도록 설정할 수 있습니다. 그러나 특수 커널 APC를 사용하지 않도록 설정하면 안 됩니다.

CallbackData가 필터 관리자 IRP 작업을 나타내지만 CallbackData 구조의 IRP가 NULL인 경우 FltCancellableWaitForMultipleObjects는 디버그 빌드에서 어설션됩니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista
대상 플랫폼	유니버설
헤더	fltkernel.h(Ntifs.h, Fltkernel.h 포함)
라이브러리	Fltmgr.lib
IRQL	설명 섹션을 참조하십시오.