FsRtlCheckOplockEx 함수(ntifs.h)

아티클
10/04/2023

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

구문

NTSTATUS FsRtlCheckOplockEx(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in, optional] PVOID                         Context,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine
);

매개 변수

[in] Oplock

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

[in] Irp

I/O 작업에 대한 IRP에 대한 포인터입니다.

[in] Flags

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

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

[in, optional] Context

CompletionRoutine 및 PostIrpRoutine 매개 변수가 가리키는 콜백 루틴에 전달할 호출자 정의 컨텍스트 정보에 대한 포인터입니다.

[in, optional] CompletionRoutine

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

이 루틴은 다음과 같이 선언됩니다.

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

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

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

[in, optional] PostIrpRoutine

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

이 루틴은 다음과 같이 선언됩니다.

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

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

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

반환 값

FsRtlCheckOplockEx 는 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	기회 잠금 중단이 진행 중입니다. IRP는 IRP_MJ_CREATE 요청이며 FILE_COMPLETE_IF_OPLOCKED 작업에 대한 create options 매개 변수에 지정되었습니다. STATUS_OPLOCK_BREAK_IN_PROGRESS OPLOCK_FLAG_COMPLETE_IF_OPLOCKED 설정되고 기회 잠금이 끊어진 경우 반환되는 성공 코드입니다.
STATUS_PENDING	기회 잠금 중단이 시작되었으며 IRP의 제어가 oplock 패키지에 전달되었습니다. CompletionRoutine이 NULL인 경우 이 루틴은 oplock 중단이 처리되는 동안 STATUS_PENDING 반환하지 않고 차단합니다. STATUS_PENDING 성공 코드입니다.

설명

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

I/O 작업으로 인해 기회 잠금이 중단되면 기회 잠금 중단이 시작됩니다.
기회 잠금 중단이 완료되고 CompletionRoutine 의 완료 루틴이 지정될 때까지 I/O 작업을 계속할 수 없는 경우 FsRtlCheckOplockEx 는 STATUS_PENDING 반환하고 PostIrpRoutine에 지정된 콜백 루틴을 호출합니다. 기회 잠금 중단이 승인되면 CompletionRoutine 의 콜백 루틴이 호출됩니다.
기회 잠금 중단이 완료되고 CompletionRoutine 이 지정되지 않을 때까지 I/O 작업을 계속할 수 없는 경우 FsRtlCheckOplockEx 는 기회 잠금 중단이 승인될 때까지 반환되지 않습니다.

CompletionRoutine이 지정된 경우에만 PostIrpRoutine을 지정해야 합니다.

파일 시스템 또는 필터 드라이버가 기회 잠금을 사용하는 경우 기회 잠금 중단을 일으킬 수 있는 I/O 작업에 대한 디스패치 루틴에서 FsRtlCheckOplockEx 를 호출해야 합니다. 이 규칙은 다음과 같은 유형의 I/O 작업에 적용됩니다. 이러한 작업으로 인해 기회 잠금 중단이 발생할 수 있기 때문입니다.

IRP_MJ_CLEANUP
IRP_MJ_CREATE
IRP_MJ_FILE_SYSTEM_CONTROL
IRP_MJ_FLUSH_BUFFERS
IRP_MJ_LOCK_CONTROL
IRP_MJ_READ
IRP_MJ_SET_INFORMATION
IRP_MJ_WRITE

기회 잠금에 대한 자세한 내용은 Microsoft Windows SDK 설명서를 참조하세요.

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

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista
대상 플랫폼	유니버설
헤더	ntifs.h(Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL