CfOpenFileWithOplock-Funktion (cfapi.h)

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

Syntax

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

Die Parameter

[in] FilePath

Vollqualifizierter Pfad zur Zu öffnenden Datei oder des Verzeichnisses.

[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 ist, gibt die API ein Share-None-Handle zurück und fordert einen RH an (OPLOCK_LEVEL_CACHE_READ|OPLOCK_LEVEL_CACHE_HANDLE) Oplock für die Datei; andernfalls wird ein Freigabe-All-Handle geöffnet, und ein R (OPLOCK_LEVEL_CACHE_READ) wird angefordert.

  1. Wenn CF_OPEN_FILE_FLAG_EXCLUSIVE angegeben ist, ist das Öffnen "Keine teilen" und erhält ein (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock.
     • Ein normaler CreateFile-Aufruf , der für einen der FILE_EXECUTE geöffnet wird | FILE_READ_DATA | FILE_WRITE_DATA | FILE_APPEND_DATA | DELETE (oder beides von GENERIC_READ | GENERIC_WRITE) wird die Oplock aufgrund des Freigabekonflikts unterbrechen. Der Oplock-Besitzer wird fertig stellen und bestätigen.
  2. Wenn CF_OPEN_FILE_FLAG_EXCLUSIVE nicht angegeben ist, ist das Öffnen "Alle teilen" und erhält ein OPLOCK_LEVEL_CACHE_READ Oplock.
     • Bei einem normalen CreateFile-Aufruf wird der Oplock nicht abgebrochen.
     • Wenn die normale CreateFile einen Freigabemodus angibt, der mit dem Zugriff des Cf-Handles in Konflikt steht (z. B. wenn die normale CreateFile nicht FILE_SHARE_READ angibt), schlägt die normale CreateFile mit ERROR_SHARING_VIOLATION fehl.
     • Der Oplock wird erst abgebrochen, wenn der andere Aufrufer eine widersprüchliche E/A ausgibt, z. B. einen Schreibvorgang. Wenn dies geschieht, ist die Oplock-Unterbrechung nur beratend.

• Wenn CF_OPEN_FILE_FLAG_WRITE_ACCESS angegeben ist, 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 kein Oplock an. Dies sollte verwendet werden, wenn der Aufrufer als Vordergrundanwendung fungiert. d. h., sie kümmern sich nicht darum, ob das von dieser API erstellte Dateihandle zu Freigabeverletzungen für andere Aufrufer führt, und sie kümmern sich nicht darum, oplocks zu unterbrechen, die sich möglicherweise bereits in der Datei befinden. So öffnen sie den Handle, ohne einen Oplock anzufordern.

  Hinweis

  Das Standardhintergrundverhalten fordert beim Öffnen des Dateihandle ein Oplock an, sodass ihr Aufruf fehlschlägt, wenn bereits ein Oplock vorhanden ist, und er kann angewiesen werden, den Handle zu schließen, wenn er sich nicht mehr auf die Art und Weise entfernen muss, um später eine Freigabeverletzung zu vermeiden.

  Sofern der Aufrufer nicht CF_OPEN_FILE_FLAG_EXCLUSIVE für CfOpenFileWithOplock angibt, wird der abgerufene Oplock nur OPLOCK_LEVEL_CACHE_READ, nicht (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE), sodass der Freigabeverletzungsschutz für eine Hintergrund-App normalerweise nicht angezeigt wird.

[out] ProtectedHandle

Ein undurchsichtiges Handle für die soeben geöffnete Datei oder das Verzeichnis. 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 sie zurückgegeben S_OK. Andernfalls wird ein HRESULT- Fehlercode zurückgegeben.

Bemerkungen

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

Dies zielt darauf ab, die Komplexität im Zusammenhang mit oplock-Nutzungen zu beseitigen. Der Aufrufer muss das von CfOpenFileWithOplock zurückgegebene Handle mit CfCloseHandle schließen.

Eine Hintergrundanwendung möchte in der Regel transparent auf Dateien ausgeführt werden. Insbesondere möchten sie verhindern, dass freigabeverstöße für andere (Vordergrund-) Öffnungen verursacht werden. Dazu nehmen sie eine (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock, z. B. durch Verwendung von CF_OPEN_FILE_FLAG_EXCLUSIVE mit CfOpenFileWithOplock. Wenn anschließend ein anderer Opener mit den angeforderten Freigabe-/Zugriffsmodi in Konflikt mit den Hintergrund-App-Modi steht, wird die Oplock-Sperre der Hintergrund-App unterbrochen. Dadurch wird die Hintergrund-App aufgefordert, den Dateihandle zu schließen (für ein Cf-Handle, das dazu führt, dass es ungültig wird – das eigentliche zugrunde liegende Handle wurde geschlossen). Sobald die Hintergrund-App den Ziehpunkt schließt, wird das geöffnete Öffnen des anderen Öffnens fortgesetzt, ohne dass die Freigabeverletzung auftritt. Das alles funktioniert aufgrund des OPLOCK_LEVEL_CACHE_HANDLE Teils des Oplocks. Ohne CF_OPEN_FILE_FLAG_EXCLUSIVE hat der Oplock nur OPLOCK_LEVEL_CACHE_READ Schutz, sodass der beschriebene Schutz gegen die Freigabeverletzung nicht erfolgt.

Anforderungen

Siehe auch

CfCloseHandle

CreateFile-