Funzione CfOpenFileWithOplock (cfapi.h)

Apre un handle opaco asincrono in un file o in una directory (sia per i file normali che per i file segnaposto) e imposta un oplock appropriato in base ai flag aperti.

Sintassi

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

Parametri

[in] FilePath

Percorso completo del file o della directory da aprire.

[in] Flags

Flag per specificare le autorizzazioni per l'apertura del file. I flag possono essere impostati su una combinazione dei valori seguenti:

• Se viene specificato CF_OPEN_FILE_FLAG_EXCLUSIVE, l'API restituisce un handle di condivisione none e richiede un rh (OPLOCK_LEVEL_CACHE_READ|OPLOCK_LEVEL_CACHE_HANDLE) oplock sul file; in caso contrario, viene aperto un handle di condivisione e viene richiesto un R (OPLOCK_LEVEL_CACHE_READ).

  1. Se si specifica CF_OPEN_FILE_FLAG_EXCLUSIVE , l'apertura è "condivisione none" e ottiene un oggetto (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock.
     • Normale chiamata CreateFile aperta per qualsiasi FILE_EXECUTE | FILE_READ_DATA | FILE_WRITE_DATA | FILE_APPEND_DATA | DELETE (o entrambe le GENERIC_READ | GENERIC_WRITE) interromperà il blocco a causa del conflitto di condivisione. Il proprietario dell'oplock verrà completato e riconosciuto.
  2. Se non viene specificato CF_OPEN_FILE_FLAG_EXCLUSIVE, l'apertura è "condividi tutto" e ottiene un OPLOCK_LEVEL_CACHE_READ oplock.
     • Una normale chiamata CreateFile non interromperà l'oplock.
     • Se il file CreateFile normale specifica una modalità di condivisione in conflitto con l'accesso dell'handle cf (ad esempio, se il normale CreateFile non specifica FILE_SHARE_READ), il normale CreateFile avrà esito negativo con ERROR_SHARING_VIOLATION.
     • L'oplock non si interrompe finché l'altro chiamante non genera un I/O in conflitto, ad esempio una scrittura. In questo caso, l'interruzione di oplock è solo consultiva.

• Se viene specificato CF_OPEN_FILE_FLAG_WRITE_ACCESS , l'API tenta di aprire il file o la directory con FILE_READ_DATA/FILE_LIST_DIRECTORY e FILE_WRITE_DATA/FILE_ADD_FILE l'accesso. In caso contrario, l'API tenta di aprire il file o la directory con FILE_READ_DATA/FILE_LIST_DIRECTORY.

• Se viene specificato CF_OPEN_FILE_FLAG_DELETE_ACCESS , l'API tenta di aprire il file o la directory con l'accesso DELETE ; in caso contrario, apre il file normalmente.

• Se viene specificato CF_OPEN_FILE_FLAG_FOREGROUND , CfOpenFileWithOplock non richiede un oplock. Questa operazione deve essere usata quando il chiamante funge da applicazione in primo piano. Ad esempio, non importa se l'handle di file creato da questa API causa violazioni di condivisione per altri chiamanti e non è importante interrompere eventuali oplock che potrebbero essere già presenti nel file. Quindi, aprono l'handle senza richiedere un oplock.

  Nota

  Il comportamento in background predefinito richiede un oplock all'apertura dell'handle di file in modo che la chiamata non riesca se è già presente un oplock e può essere indicato di chiudere l'handle se è necessario uscire dal modo per evitare di causare una violazione di condivisione in un secondo momento.

  A meno che il chiamante non specifichi CF_OPEN_FILE_FLAG_EXCLUSIVEa CfOpenFileWithOplock, l'oplock che otterrà sarà solo OPLOCK_LEVEL_CACHE_READ, non (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE), quindi non ci sarà la protezione delle violazioni di condivisione che un'app in background potrebbe normalmente volere.

[out] ProtectedHandle

Handle opaco per il file o la directory appena aperta. Si noti che questo non è un normale handle Win32 e quindi non può essere usato direttamente con API Win32 non CfApi.

Valore restituito

Se questa funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

Quando l'oplock viene interrotto, l'API gestirà automaticamente la notifica di interruzione per conto del chiamante svuotando tutte le richieste attive e quindi chiudendo l'handle Win32 sottostante.

Ciò mira a rimuovere la complessità correlata agli utilizzi di oplock. Il chiamante deve chiudere l'handle restituito da CfOpenFileWithOplock con CfCloseHandle.

Un'applicazione in background in genere vuole operare in modo trasparente sui file. In particolare, vogliono evitare di causare violazioni di condivisione ad altri opener (in primo piano). A tale scopo, accettano un (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock, ad esempio viene concesso usando CF_OPEN_FILE_FLAG_EXCLUSIVE con CfOpenFileWithOplock. Se successivamente viene eseguito un altro opener le cui modalità di condivisione/accesso richieste sono in conflitto con l'app in background, l'app in background si interrompe. In questo modo viene richiesto all'app in background di chiudere il relativo handle di file (per un handle Cf, che ne causa la mancata validità, ovvero l'handle sottostante reale è stato chiuso). Una volta chiusa l'handle dell'app in background, l'altro opener procede senza riscontrare la violazione di condivisione. Tutto questo funziona a causa della OPLOCK_LEVEL_CACHE_HANDLE parte dell'oplock. Senza CF_OPEN_FILE_FLAG_EXCLUSIVE, l'oplock ha solo OPLOCK_LEVEL_CACHE_READ protezione, quindi la protezione delle violazioni di condivisione descritta non si verifica.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 10 versione 1709 [solo app desktop]
Server minimo supportato	Windows Server 2016 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	cfapi.h
Libreria	CldApi.lib
DLL	CldApi.dll

Vedi anche

CfCloseHandle

CreateFile