FsRtlCheckOplockEx2 함수(ntifs.h)

아티클
08/07/2023

FsRtlCheckOplockEx2 는 파일 I/O 작업에 대한 IRP를 파일의 현재 기회 잠금(oplock) 상태와 동기화합니다.

구문

NTSTATUS FsRtlCheckOplockEx2(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in]           ULONG                         FlagsEx2,
  [in, optional] PVOID                         CompletionRoutineContext,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine,
  [in]           ULONGLONG                     Timeout,
  [in, optional] PVOID                         NotifyContext,
  [in, optional] POPLOCK_NOTIFY_ROUTINE        NotifyRoutine
);

매개 변수

[in] Oplock

파일의 불투명 불투명 구조체에 대한 포인터입니다. 이 포인터는 FsRtlInitializeOplock에 대한 이전 호출에 의해 초기화되어야 합니다.

[in] Irp

요청된 I/O 작업을 선언하는 IRP에 대한 포인터입니다.

[in] Flags

연결된 파일 I/O 작업에 대한 비트 마스크입니다. 파일 시스템 또는 필터 드라이버는 FsRtlCheckOplockEx2의 동작을 지정하는 비트를 설정합니다. 플래그 에는 다음과 같은 옵션이 있습니다.

플래그 값	의미
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED(0x00000001)	oplock 중단을 발생시킨 작업을 차단하거나 보류하지 않고 oplock 중단을 진행할 수 있도록 지정합니다.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY(0x00000002)	FsRtlCheckOplockEx2는 Irp 매개 변수가 가리키는 IRP와 연결된 FILE_OBJECT oplock 키에 대해서만 검사 지정합니다. 그런 다음, IRP에 키를 제공하는 경우 FsRtlCheckOplockEx2에서 키를 추가해야 합니다. 다른 oplock 처리는 발생하지 않습니다. 즉, oplock 중단이 발생하지 않습니다. Windows 7부터 지원됩니다.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK(0x00000004)	FsRtlCheckOplockEx2가 FsRtlOplockFsctrl 루틴에 대한 호출을 통해 이전에 설정된 상태를 되돌리기 지정합니다. FsRtlOplockFsctrl 은 create options 매개 변수에서 FILE_OPEN_REQUIRING_OPLOCK 플래그를 지정하는 IRP_MJ_CREATE 요청을 처리하는 동안 호출됩니다. OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK 플래그는 일반적으로 이전에 실패한 경우 이러한 만들기 요청의 최종 처리에 사용됩니다. Windows 7부터 지원됩니다.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS(0x00000008)	oplock 키에 관계없이 모든 oplock 나누기를 계속 진행하도록 지정합니다. Windows 7부터 지원됩니다.
OPLOCK_FLAG_PARENT_OBJECT(0x00000010)	Oplock이 Irp 매개 변수의 IRP가 전달되는 파일 또는 디렉터리의 부모(디렉터리)와 연결되도록 지정합니다. Windows 8 부터 지원합니다.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE(0x00000020)	Irp에 지정된 I/O 작업이 원래 만들기 옵션에 설정된 FILE_DELETE_ON_CLOSE 플래그로 열린 핸들에 대한 IRP_MJ_CLEANUP 지정합니다. Irp가 IRP_MJ_CLEANUP 작업이 아닌 경우 이 플래그는 효과가 없습니다. 이 플래그를 지정하면 oplock 중단이 발생할 수 있습니다. Windows 8 부터 지원합니다.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK(0x00000040)	해당 디렉터리에서 파일 또는 링크를 삭제할 때 부모 디렉터리에서 oplock 중단 처리를 지정합니다. 지정된 경우 이 플래그를 OPLOCK_FLAG_PARENT_OBJECT 함께 사용해야 합니다. 이 플래그는 파일 시스템에서 링크 또는 파일이 제거되는 작업을 처리할 때 지정해야 합니다. Windows 8 부터 지원합니다.

[in] FlagsEx2

예약; 를 0으로 설정해야 합니다.

[in, optional] CompletionRoutineContext

CompletionRoutine 매개 변수가 가리키는 콜백 루틴에 전달할 호출자 정의 컨텍스트 정보에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

[in, optional] CompletionRoutine

호출자가 제공한 콜백 루틴에 대한 포인터입니다. oplock 중단이 진행 중인 경우 중단이 완료되면 이 루틴이 호출됩니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. NULL인 경우 FsRtlCheckOpLockEx2는 동기적으로 작동하여 oplock 중단이 완료될 때까지 호출자를 대기 상태로 전환합니다.

CompletionRoutine 은 다음과 같이 선언됩니다.

typedef VOID
(*POPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PVOID Context,
      IN PIRP Irp
      );

CompletionRoutine 에는 다음과 같은 매개 변수가 있습니다.

컨텍스트: Context 매개 변수에서 FsRtlCheckOplockEx2에 전달된 컨텍스트 정보 포인터입니다.
Irp: I/O 작업에 대한 IRP에 대한 포인터입니다.

[in, optional] PostIrpRoutine

I/O 작업이 작업 큐에 게시되는 경우 호출자가 제공한 콜백 루틴에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

PostIrpRoutine 은 다음과 같이 선언됩니다.

typedef VOID
(*POPLOCK_FS_PREPOST_IRP) (
      IN PVOID Context,
      IN PIRP Irp
      );

PostIrpRoutine 에는 다음과 같은 매개 변수가 있습니다.

컨텍스트- 컨텍스트 매개 변수에서 FsRtlCheckOplockEx2에 전달된 컨텍스트 정보 포인터입니다.
Irp: I/O 작업에 대한 IRP에 대한 포인터입니다.

[in] Timeout

0이 아닌 경우 oplock 중단이 완료되기를 기다리기 위해 호출자의 스레드를 차단하는 데 사용되는 이벤트를 대기할 시간 제한(밀리초)을 지정합니다. 이 값은 다음 조건이 모두 충족되지 않는 한 무시됩니다. CompletionRoutine 은 NULL이고 NotifyRoutine 은 NULL이 아닙니다.

[in, optional] NotifyContext

NotifyRoutine 매개 변수가 가리키는 콜백 루틴에 전달할 OPLOCK_NOTIFY_PARAMS 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

[in, optional] NotifyRoutine

oplock 상태 알림을 위해 호출할 호출자 제공 콜백 루틴에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

NotifyRoutine 은 다음과 같이 선언됩니다.

typedef NTSTATUS
(*POPLOCK_NOTIFY_ROUTINE) (
      IN POPLOCK_NOTIFY_PARAMS NotifyParams
      );

NotifyRoutine 에는 다음과 같은 매개 변수가 있습니다.

NotifyParams- FsRtlCheckOplockEx2에 전달된 NotifyContext 매개 변수로 설정됩니다.

반환 값

FsRtlCheckOplockEx2 는 STATUS_SUCCESS 또는 다음 중 하나와 같은 적절한 NTSTATUS 코드를 반환합니다.

반환 코드	설명
STATUS_CANCELLED	IRP가 취소되었습니다. STATUS_CANCELLED 오류 코드입니다.
STATUS_CANNOT_BREAK_OPLOCK	oplock 중단을 수행할 수 없습니다. IRP는 IRP_MJ_CREATE 요청입니다. FILE_OPEN_REQUIRING_OPLOCK 작업에 대한 create options 매개 변수에 지정되었으며 oplock이 부여되었습니다.
STATUS_OPLOCK_BREAK_IN_PROGRESS	oplock 중단이 진행 중입니다. IRP는 IRP_MJ_CREATE 요청이며 FILE_COMPLETE_IF_OPLOCKED 작업에 대한 create options 매개 변수에 지정되었습니다. STATUS_OPLOCK_BREAK_IN_PROGRESS OPLOCK_FLAG_COMPLETE_IF_OPLOCKED 설정되고 oplock이 끊어진 경우 반환되는 성공 코드입니다.
STATUS_PENDING	oplock 중단이 진행 중이며 IRP 제어가 oplock 패키지에 전달되었습니다. CompletionRoutine이 NULL이면 oplock 중단이 STATUS_PENDING 반환하지 않고 처리되는 동안 FsRtlCheckOplockEx2가 차단됩니다. STATUS_PENDING 성공 코드입니다.

설명

미니필터는 FsRtlCheckOplockEx2 대신 FltCheckOplockEx를 호출해야 합니다.

FsRtlCheckOplockEx2 는 I/O 작업에 대한 IRP를 다음 조건에 따라 파일의 현재 oplock 상태와 동기화합니다.

I/O 작업으로 인해 oplock이 중단되면 oplock 중단이 시작됩니다.
Oplock 중단이 완료되고 CompletionRoutine 의 완료 루틴이 지정될 때까지 I/O 작업을 계속할 수 없는 경우 FsRtlCheckOplockEx2 는 STATUS_PENDING 반환하고 PostIrpRoutine에 지정된 콜백 루틴을 호출합니다. oplock 중단이 승인되면 CompletionRoutine 의 콜백 루틴이 호출됩니다.
oplock 중단이 완료되고 CompletionRoutine 이 지정되지 않을 때까지 I/O 작업을 계속할 수 없는 경우 호출자의 스레드가 차단되고 Oplock 중단이 완료된 경우에만 FsRtlCheckOplockEx2 가 반환됩니다.

호출자의 스레드가 차단되고 NotifyRoutine이 NULL이 아닌 경우 NotifyParams에 설정된 다음 이유 중 전부 또는 모두에 대해 NotifyRoutine이 호출됩니다.

OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT
OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED

위의 이유로 NotifyRoutine 에 대한 호출은 CompletionRoutine 이 NULL이고 중단이 완료될 때까지 대기하도록 호출자의 스레드를 차단해야 하는 경우에만 발생합니다.

NotifyRoutine이 OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT 이유로 호출되는 경우 어떤 이유로든 대기가 종료/완료될 경우(절대로 가능하지 않을 수 있음) OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED 이유로 항상 호출됩니다.

FsRtlCheckOplockEx2는 NotifyRoutine에서 반환된 OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT 및 OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED 상태 코드를 무시합니다.

CompletionRoutine이 지정된 경우에만 PostIrpRoutine을 지정해야 합니다. PostIrpRoutine이 NULL이 아닌 경우 대기 중인 Irp 큐에 대기하기 전에 호출됩니다.

플래그 에 OPLOCK_FLAG_PARENT_OBJECT 플래그를 지정하면 FsRtlCheckOplockEx2 는 기존 부모 oplock을 무조건 중단합니다. 즉, Irp 의 주 코드는 고려되지 않습니다.

파일 시스템에서 oplock을 사용하는 경우 oplock 중단을 일으킬 수 있는 I/O 작업에 대한 디스패치 루틴에서 FsRtlCheckOplockEx2 를 호출해야 합니다. 이 규칙은 다음 유형의 I/O 작업에 적용됩니다. 이러한 작업으로 인해 오프록 중단이 발생할 수 있기 때문입니다.