LockFileEx-Funktion (fileapi.h)
Sperrt die angegebene Datei für den exklusiven Zugriff durch den aufrufenden Prozess. Diese Funktion kann entweder synchron oder asynchron ausgeführt werden und eine exklusive oder eine gemeinsame Sperre anfordern.
Syntax
BOOL LockFileEx(
[in] HANDLE hFile,
[in] DWORD dwFlags,
DWORD dwReserved,
[in] DWORD nNumberOfBytesToLockLow,
[in] DWORD nNumberOfBytesToLockHigh,
[in, out] LPOVERLAPPED lpOverlapped
);
Parameter
[in] hFile
Ein Handle zur Datei. Das Handle muss mit dem zugriffsrecht GENERIC_READ oder GENERIC_WRITE erstellt worden sein. Weitere Informationen finden Sie unter Dateisicherheit und Zugriffsrechte.
[in] dwFlags
Dieser Parameter kann mindestens einer der folgenden Werte sein.
dwReserved
Reservierter Parameter; muss auf 0 festgelegt werden.
[in] nNumberOfBytesToLockLow
Die 32 Bit der Länge des zu sperrenden Bytebereichs in niedriger Reihenfolge.
[in] nNumberOfBytesToLockHigh
Die hohen 32 Bits der Länge des zu sperrenden Bytebereichs.
[in, out] lpOverlapped
Ein Zeiger auf eine ÜBERLAPPENDE Struktur, die die Funktion mit der Sperranforderung verwendet. Diese erforderliche Struktur enthält den Dateioffset des Anfangs des Sperrbereichs. Sie müssen das hEvent-Element mit einem gültigen Handle oder null initialisieren.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert nonzero (TRUE).
Wenn die Funktion fehlschlägt, ist der Rückgabewert 0 (FALSE). Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Hinweise
Das Sperren einer Region einer Datei wird verwendet, um mithilfe dieses Dateihandles freigegebenen oder exklusiven Zugriff auf die angegebene Region zu erhalten. Wenn das Dateihandle von einem Prozess geerbt wird, der durch den Sperrprozess erstellt wurde, wird dem untergeordneten Prozess kein Zugriff auf die gesperrte Region gewährt. Wenn der Sperrvorgang die Datei ein zweites Mal öffnet, kann er nicht über dieses zweite Handle auf die angegebene Region zugreifen, bis die Region entsperrt wird.
Das Sperren eines Teils einer Datei für den exklusiven Zugriff verweigert allen anderen Prozessen sowohl Lese- als auch Schreibzugriff auf den angegebenen Bereich der Datei. Das Sperren einer Region, die über die aktuelle Dateiendeposition hinausgeht, ist kein Fehler.
Das Sperren eines Teils einer Datei für den freigegebenen Zugriff verweigert allen Prozessen den Schreibzugriff auf den angegebenen Bereich der Datei, einschließlich des Prozesses, der die Region zuerst sperrt. Alle Prozesse können die gesperrte Region lesen.
Das Sperren einer Region einer Datei verhindert nicht das Lesen oder Schreiben aus einer zugeordneten Dateiansicht.
Die LockFileEx-Funktion funktioniert asynchron, wenn das Dateihandle für asynchrone E/A-Vorgänge geöffnet wurde, es sei denn, das flag LOCKFILE_FAIL_IMMEDIATELY ist angegeben. Wenn eine exklusive Sperre für einen Bereich einer Datei angefordert wird, der bereits über eine freigegebene oder exklusive Sperre verfügt, gibt die Funktion den Fehler ERROR_IO_PENDING zurück. Das System signalisiert das in der OVERLAPPED-Struktur angegebene Ereignis, nachdem die Sperre gewährt wurde. Um zu bestimmen, wann die Sperre gewährt wurde, verwenden Sie die GetOverlappedResult-Funktion oder eine der Wartefunktionen. Weitere Informationen finden Sie unter Synchrone und asynchrone E/A.
Wenn das Dateihandle nicht für asynchrone E/A-Vorgänge geöffnet wurde und die Sperre nicht verfügbar ist, wartet dieser Aufruf, bis die Sperre gewährt wird oder ein Fehler auftritt, es sei denn, das flag LOCKFILE_FAIL_IMMEDIATELY ist angegeben.
Exklusive Sperren können einen vorhandenen gesperrten Bereich einer Datei nicht überlappen. Freigegebene Sperren können eine gesperrte Region überlappen, sofern für diese Region gespeicherte Sperren freigegebene Sperren sind. Eine freigegebene Sperre kann eine exklusive Sperre überlappen, wenn beide Sperren mit demselben Dateihandle erstellt wurden. Wenn eine freigegebene Sperre eine exklusive Sperre überschneidet, ist der einzige mögliche Zugriff ein Lesezugriff durch den Besitzer der Sperren. Wenn derselbe Bereich mit einer exklusiven und einer freigegebenen Sperre gesperrt ist, sind zwei Entsperrvorgänge erforderlich, um die Region zu entsperren. Der erste Entsperrvorgang entsperrt die exklusive Sperre, der zweite Entsperrvorgang die freigegebene Sperre.
Wenn ein Prozess beendet wird, wenn ein Teil einer Datei gesperrt ist oder eine Datei mit ausstehenden Sperren geschlossen wird, werden die Sperren vom Betriebssystem entsperrt. Die Zeit, die das Betriebssystem benötigt, um diese Sperren zu entsperren, hängt jedoch von den verfügbaren Systemressourcen ab. Daher wird empfohlen, dass Ihr Prozess alle Dateien explizit entsperrt, die er beim Beenden gesperrt hat. Wenn dies nicht geschieht, kann der Zugriff auf diese Dateien verweigert werden, wenn das Betriebssystem sie noch nicht entsperrt hat.
Unter Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.
| Technologie | Unterstützt |
|---|---|
| SMB 3.0-Protokoll (Server Message Block) | Ja |
| SMB 3.0 Transparent Failover (TFO) | Ja |
| SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO) | Ja |
| Dateisystem mit freigegebenen Clustervolumes (CsvFS) | Ja |
| Robustes Dateisystem (Resilient File System, ReFS) | Ja |
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | fileapi.h (Einschließen von Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |