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 は share-none ハンドルを返し、RH (OPLOCK_LEVEL_CACHE_READ|OPLOCK_LEVEL_CACHE_HANDLE) ファイルの oplock。それ以外の場合は、共有すべてのハンドルが開き、R (OPLOCK_LEVEL_CACHE_READ) が要求されます。

    1. CF_OPEN_FILE_FLAG_EXCLUSIVEが指定されている場合、開いているは "share none" であり、 (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 ハンドルのアクセスと競合する共有モードが指定されている場合 (たとえば、通常の CreateFile でFILE_SHARE_READが指定されていない場合)、通常の CreateFile はERROR_SHARING_VIOLATIONで失敗します。
      • oplock は、他の呼び出し元が書き込みなどの競合する I/O を発行するまで中断しません。 その場合、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を使用して付与されます。 その後、要求された共有/アクセス モードがバックグラウンド アプリと競合する別の opener が表示された場合、バックグラウンド アプリの 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
Library CldApi.lib
[DLL] CldApi.dll

こちらもご覧ください

CfCloseHandle

CreateFile