FsRtlCheckOplockEx 함수(ntifs.h)

아티클
12/21/2024

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부터 지원됩니다. FsRtlCheckOplockExIrp 매개 변수가 가리키는 IRP와 연결된 FILE_OBJECT 기회 잠금 키만 확인하도록 지정합니다. FsRtlCheckOplockEx IRP에 제공된 경우 키를 추가해야 합니다. 다른 oplock 처리는 발생하지 않습니다. 즉, 기회 잠금 중단이 발생하지 않습니다.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK(0x00000004)	Windows 7부터 지원됩니다. FsRtlCheckOplockExFsRtlOplockFsctrl 루틴에 대한 호출을 통해 이전에 설정된 상태를 되돌려야 하도록 지정합니다. FsRtlOplockFsctrl 만들기 옵션 매개 변수의 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부터 지원됩니다. OplockIrp 매개 변수의 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
      );

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

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

[in, optional] PostIrpRoutine

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

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

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

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

매개 변수	묘사
문맥	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 작업에 대한 만들기 옵션 매개 변수에 지정되었으며 oplock이 부여되었습니다.
STATUS_OPLOCK_BREAK_IN_PROGRESS	기회 잠금 중단이 진행 중입니다. IRP는 IRP_MJ_CREATE 요청이며 FILE_COMPLETE_IF_OPLOCKED 작업에 대한 만들기 옵션 매개 변수에 지정되었습니다. 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