CfOpenFileWithOplock 함수(cfapi.h)

파일 또는 디렉터리(일반 및 자리 표시자 파일 모두)에 대한 비동기 불투명 핸들을 열고 열린 플래그에 따라 적절한 oplock을 설정합니다.

구문

HRESULT CfOpenFileWithOplock(
  [in]  LPCWSTR            FilePath,
  [in]  CF_OPEN_FILE_FLAGS Flags,
  [out] PHANDLE            ProtectedHandle
);

매개 변수

[in] FilePath

열 파일 또는 디렉터리에 대한 정규화된 경로입니다.

[in] Flags

파일 열기에 대한 권한을 지정하는 플래그입니다. 플래그 는 다음 값의 조합으로 설정할 수 있습니다.

• CF_OPEN_FILE_FLAG_EXCLUSIVE 지정하면 API는 공유 없음 핸들을 반환하고 RH(OPLOCK_LEVEL_CACHE_READ|OPLOCK_LEVEL_CACHE_HANDLE) 파일의 oplock; 그렇지 않으면 모든 공유 핸들이 열리고 R(OPLOCK_LEVEL_CACHE_READ)이 요청됩니다.

  1. CF_OPEN_FILE_FLAG_EXCLUSIVE 지정하면 열기가 "공유 없음"이고 (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock입니다.
     • FILE_EXECUTE |에 대해 열리는 일반적인 CreateFile 호출 FILE_READ_DATA | FILE_WRITE_DATA | FILE_APPEND_DATA | DELETE(또는 GENERIC_READ 중 하나/둘 다 | GENERIC_WRITE)은 공유 충돌로 인해 oplock을 중단합니다. oplock 소유자는 완료하고 인정하게 됩니다.
  2. CF_OPEN_FILE_FLAG_EXCLUSIVE 지정되지 않은 경우 열기는 "모두 공유"이며 OPLOCK_LEVEL_CACHE_READ oplock을 가져옵니다.
     • 일반적인 CreateFile 호출은 oplock을 중단하지 않습니다.
     • 일반 CreateFile이 Cf 핸들의 액세스와 충돌하는 공유 모드를 지정하는 경우(instance 경우 일반 CreateFile에서 FILE_SHARE_READ 지정하지 않는 경우) 일반 CreateFile은 ERROR_SHARING_VIOLATION 함께 실패합니다.
     • 다른 호출자가 쓰기와 같은 충돌하는 I/O를 발급할 때까지 oplock이 중단되지 않습니다. 이 경우 oplock 중단은 권고에만 해당됩니다.

• CF_OPEN_FILE_FLAG_WRITE_ACCESS 지정되면 API는FILE_READ_DATA FILE_LIST_DIRECTORY/ 사용하여 파일 또는 디렉터리를 열고 FILE_ADD_FILE 액세스를 FILE_WRITE_DATA/, 그렇지 않으면 API가FILE_READ_DATA FILE_LIST_DIRECTORY/ 파일 또는 디렉터리를 열려고 시도합니다.

• CF_OPEN_FILE_FLAG_DELETE_ACCESS 지정한 경우 API는 DELETE 액세스 권한이 있는 파일 또는 디렉터리를 열려고 시도합니다. 그렇지 않으면 파일이 정상적으로 열립니다.

• CF_OPEN_FILE_FLAG_FOREGROUND 지정한 경우 CfOpenFileWithOplock은 oplock을 요청하지 않습니다. 호출자가 포그라운드 애플리케이션 역할을 할 때 사용해야 합니다. 즉, 이 API에서 만든 파일 핸들이 다른 호출자에 대한 공유 위반을 일으키는지 여부를 신경 쓰지 않으며 이미 파일에 있을 수 있는 oplock을 위반하는 것에 대해 신경 쓰지 않습니다. 따라서 oplock을 요청하지 않고 핸들을 엽니다.

  참고

  기본 백그라운드 동작은 파일 핸들을 열 때 oplock을 요청하므로 이미 oplock이 있는 경우 호출이 실패하고 나중에 공유 위반이 발생하지 않도록 하려면 핸들을 닫으라는 지시를 받을 수 있습니다.

  호출자가 CfOpenFileWithOplock에 대한 CF_OPEN_FILE_FLAG_EXCLUSIVE 지정하지 않는 한 가져오는 oplock은 OPLOCK_LEVEL_CACHE_READ(OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE)이므로 백그라운드 앱이 일반적으로 원할 수 있는 공유 위반 보호가 없습니다.

[out] ProtectedHandle

방금 열린 파일 또는 디렉터리에 대한 불투명 핸들입니다. 이는 일반적인 Win32 핸들이 아니므로 비 CfApi Win32 API에서 직접 사용할 수 없습니다.

반환 값

이 함수가 성공하면 를 반환합니다 S_OK. 그러지 않으면 HRESULT 오류 코드를 반환합니다.

설명

oplock이 끊어지면 API는 모든 활성 요청을 드레이닝한 다음 기본 Win32 핸들을 닫아 호출자를 대신하여 자동으로 중단 알림을 처리합니다.

이는 oplock 사용과 관련된 복잡성을 제거하는 것을 목표로 합니다. 호출자는 CfCloseHandle을 사용하여 CfOpenFileWithOplock에서 반환된 핸들을 닫아야 합니다.

백그라운드 애플리케이션은 일반적으로 파일에서 투명하게 작동하려고 합니다. 특히, 그들은 다른 (전경) 오프너에 공유 위반을 일으키는 것을 방지하려고합니다. 이렇게 하려면 (OPLOCK_LEVEL_CACHE_READ | 와 같은 OPLOCK_LEVEL_CACHE_HANDLE) oplock은 CfOpenFileWithOplock과 함께 CF_OPEN_FILE_FLAG_EXCLUSIVE 사용하여 부여됩니다. 이후에 요청된 공유/액세스 모드가 백그라운드 앱과 충돌하는 다른 오프너가 제공되면 백그라운드 앱의 oplock이 중단됩니다. 이렇게 하면 백그라운드 앱이 파일 핸들을 닫을지 묻는 메시지가 표시됩니다(Cf 핸들의 경우 유효하지 않은 경우 실제 기본 핸들이 닫혔습니다). 백그라운드 앱이 핸들을 닫으면 공유 위반이 발생하지 않고 다른 오프너의 열기가 진행됩니다. 이 모든 것은 oplock의 OPLOCK_LEVEL_CACHE_HANDLE 부분으로 인해 작동합니다. CF_OPEN_FILE_FLAG_EXCLUSIVE 없으면 oplock에는 OPLOCK_LEVEL_CACHE_READ 보호만 있으므로 설명된 공유 위반 보호가 발생하지 않습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 10 버전 1709 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2016 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	cfapi.h
라이브러리	CldApi.lib
DLL	CldApi.dll

추가 정보

CfCloseHandle

CreateFile