CfOpenFileWithOplock-Funktion (cfapi.h)

Artikel
02/23/2024

Öffnet ein asynchrones undurchsichtiges Handle für eine Datei oder ein Verzeichnis (sowohl für normale Dateien als auch für Platzhalterdateien) und richtet basierend auf den geöffneten Flags einen ordnungsgemäßen Oplock dafür ein.

Syntax

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

Parameter

[in] FilePath

Vollqualifizierter Pfad zu der zu öffnenden Datei oder dem Zu öffnenden Verzeichnis.

[in] Flags

Die Flags zum Angeben von Berechtigungen zum Öffnen der Datei. Flags können auf eine Kombination der folgenden Werte festgelegt werden:

Wenn CF_OPEN_FILE_FLAG_EXCLUSIVE angegeben wird, gibt die API ein Handle ohne Freigabe zurück und fordert einen RH (OPLOCK_LEVEL_CACHE_READ|OPLOCK_LEVEL_CACHE_HANDLE) oplock für die Datei; andernfalls wird ein Freigabehandle geöffnet und ein R (OPLOCK_LEVEL_CACHE_READ) angefordert.
1. Wenn CF_OPEN_FILE_FLAG_EXCLUSIVE angegeben ist, ist geöffnet "keine freigeben" und erhält einen (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock.
  - Ein normaler CreateFile-Aufruf , der für eine der FILE_EXECUTE geöffnet wird | FILE_READ_DATA | FILE_WRITE_DATA | FILE_APPEND_DATA | DELETE (oder beides von GENERIC_READ | GENERIC_WRITE) unterbricht den Oplock aufgrund des Freigabekonflikts. Der Oplock-Besitzer wird fertig und bestätigt.
2. Wenn CF_OPEN_FILE_FLAG_EXCLUSIVE nicht angegeben ist, ist "alle freigeben" geöffnet und erhält einen OPLOCK_LEVEL_CACHE_READ Oplock.
  - Ein normaler CreateFile-Aufruf unterbricht den Oplock nicht.
  - Wenn die normale CreateFile einen Freigabemodus angibt, der mit dem Zugriff des Cf-Handles in Konflikt steht (für instance, wenn die normale CreateFile nicht FILE_SHARE_READ angibt), schlägt die normale CreateFile-Datei mit ERROR_SHARING_VIOLATION fehl.
  - Der Oplock wird erst unterbrochen, wenn der andere Aufrufer eine in Konflikt stehende E/A ausgibt, z. B. einen Schreibvorgang. In diesem Fall ist der Oplock-Umbruch nur eine Empfehlung.
Wenn CF_OPEN_FILE_FLAG_WRITE_ACCESS angegeben wird, versucht die API, die Datei oder das Verzeichnis mit FILE_READ_DATA/FILE_LIST_DIRECTORY und FILE_WRITE_DATA/FILE_ADD_FILE Zugriff zu öffnen. Andernfalls versucht die API, die Datei oder das Verzeichnis mit FILE_READ_DATA FILE_LIST_DIRECTORY/ zu öffnen.
Wenn CF_OPEN_FILE_FLAG_DELETE_ACCESS angegeben ist, versucht die API, die Datei oder das Verzeichnis mit DELETE-Zugriff zu öffnen. Andernfalls wird die Datei normal geöffnet.
Wenn CF_OPEN_FILE_FLAG_FOREGROUND angegeben ist, fordert CfOpenFileWithOplock keinen oplock an. Dies sollte verwendet werden, wenn der Aufrufer als Vordergrundanwendung fungiert. d. h. es ist ihnen egal, ob das von dieser API erstellte Dateihandle Freigabeverletzungen für andere Aufrufer verursacht, und sie kümmern sich nicht darum, Oplocks zu brechen, die sich möglicherweise bereits in der Datei befinden. So öffnen sie den Handle, ohne einen Oplock anzufordern.

Hinweis

Das Standardmäßige Hintergrundverhalten fordert einen Oplock an, wenn das Dateihandle geöffnet wird, sodass der Aufruf fehlschlägt, wenn bereits ein Oplock vorhanden ist, und sie können angewiesen werden, ihren Handle zu schließen, wenn sie aus dem Weg gehen müssen, um später eine Freigabeverletzung zu vermeiden.

Sofern der Aufrufer CF_OPEN_FILE_FLAG_EXCLUSIVE zu CfOpenFileWithOplock nicht angibt, wird der abgerufene Oplock nur OPLOCK_LEVEL_CACHE_READ, nicht (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE), sodass es nicht den Für eine Hintergrund-App normalerweise gewünschten Freigabeverletzungsschutz gibt.

[out] ProtectedHandle

Ein undurchsichtiges Handle für die Datei oder das Verzeichnis, das gerade geöffnet wird. Beachten Sie, dass dies kein normales Win32-Handle ist und daher nicht direkt mit Nicht-CfApi Win32-APIs verwendet werden kann.

Rückgabewert

Wenn diese Funktion erfolgreich ist, wird zurückgegeben S_OK. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Wenn der Oplock unterbrochen wird, verarbeitet die API die Unterbrechungsbenachrichtigung automatisch im Namen des Aufrufers, indem alle aktiven Anforderungen entladen und dann das zugrunde liegende Win32-Handle geschlossen wird.

Dadurch soll die Komplexität im Zusammenhang mit oplock-Nutzungen beseitigt werden. Der Aufrufer muss das von CfOpenFileWithOplock zurückgegebene Handle mit CfCloseHandle schließen.

Eine Hintergrundanwendung möchte in der Regel transparent für Dateien arbeiten. Insbesondere möchten sie verhindern, dass es zu Verstößen gegen die Freigabe für andere (Vordergrund-)Opener führt. Dazu nehmen sie einen (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock, z. B. mithilfe von CF_OPEN_FILE_FLAG_EXCLUSIVE mit CfOpenFileWithOplock. Wenn anschließend ein anderer Opener kommt, dessen angeforderte Freigabe-/Zugriffsmodi mit den Der Hintergrund-App in Konflikt treten, wird der Oplock der Hintergrund-App unterbrochen. Dadurch wird die Hintergrund-App aufgefordert, ihr Dateihandle zu schließen (bei einem Cf-Handle wird es ungültig – das eigentliche zugrunde liegende Handle wurde geschlossen). Sobald die Hintergrund-App ihren Handle geschlossen hat, wird das Geöffnete des anderen Openers fortgesetzt, ohne dass die Freigabeverletzung auftritt. Dies alles funktioniert aufgrund des OPLOCK_LEVEL_CACHE_HANDLE Teils des Oplocks. Ohne CF_OPEN_FILE_FLAG_EXCLUSIVE verfügt der Oplock nur über OPLOCK_LEVEL_CACHE_READ Schutz, sodass der beschriebene Schutz gegen Die Freigabeverletzung nicht auftritt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 10, Version 1709 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2016 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	cfapi.h
Bibliothek	CldApi.lib
DLL	CldApi.dll

Weitere Informationen

CfCloseHandle

CreateFile

Share via