LockFileEx, fonction (fileapi.h)
Verrouille le fichier spécifié pour un accès exclusif par le processus appelant. Cette fonction peut fonctionner de manière synchrone ou asynchrone et peut demander un verrou exclusif ou partagé.
Syntaxe
BOOL LockFileEx(
[in] HANDLE hFile,
[in] DWORD dwFlags,
DWORD dwReserved,
[in] DWORD nNumberOfBytesToLockLow,
[in] DWORD nNumberOfBytesToLockHigh,
[in, out] LPOVERLAPPED lpOverlapped
);
Paramètres
[in] hFile
Descripteur du fichier. Le handle doit avoir été créé avec le droit d’accès GENERIC_READ ou GENERIC_WRITE . Pour plus d’informations, consultez Sécurité des fichiers et droits d’accès.
[in] dwFlags
Ce paramètre peut être une ou plusieurs des valeurs suivantes.
dwReserved
Paramètre réservé ; doit être défini sur zéro.
[in] nNumberOfBytesToLockLow
32 bits d’ordre inférieur de la longueur de la plage d’octets à verrouiller.
[in] nNumberOfBytesToLockHigh
32 bits d’ordre supérieur de la longueur de la plage d’octets à verrouiller.
[in, out] lpOverlapped
Pointeur vers une structure CHEVAUCHEMENT QUE la fonction utilise avec la demande de verrouillage. Cette structure, qui est obligatoire, contient le décalage de fichier du début de la plage de verrous. Vous devez initialiser le membre hEvent sur un handle valide ou zéro.
Valeur retournée
Si la fonction réussit, la valeur de retour est différente de zéro (TRUE).
Si la fonction échoue, la valeur de retour est zéro (FALSE). Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Remarques
Le verrouillage d’une région d’un fichier permet d’acquérir un accès partagé ou exclusif à la région spécifiée à l’aide de ce handle de fichier. Si le handle de fichier est hérité par un processus créé par le processus de verrouillage, le processus enfant n’a pas accès à la région verrouillée. Si le processus de verrouillage ouvre le fichier une deuxième fois, il ne peut pas accéder à la région spécifiée via ce deuxième handle tant qu’il ne déverrouille pas la région.
Le verrouillage d’une partie d’un fichier pour un accès exclusif refuse à tous les autres processus l’accès en lecture et en écriture à la région spécifiée du fichier. Le verrouillage d’une région qui dépasse la position actuelle de fin de fichier n’est pas une erreur.
Le verrouillage d’une partie d’un fichier pour l’accès partagé refuse à tous les processus l’accès en écriture à la région spécifiée du fichier, y compris le processus qui verrouille d’abord la région. Tous les processus peuvent lire la région verrouillée.
Le verrouillage d’une région d’un fichier n’empêche pas la lecture ou l’écriture à partir d’une vue de fichier mappée.
La fonction LockFileEx fonctionne de manière asynchrone si le handle de fichier a été ouvert pour les E/S asynchrones, sauf si l’indicateur LOCKFILE_FAIL_IMMEDIATELY est spécifié. Si un verrou exclusif est demandé pour une plage d’un fichier qui a déjà un verrou partagé ou exclusif, la fonction retourne l’erreur ERROR_IO_PENDING. Le système signale l’événement spécifié dans la structure OVERLAPPED une fois le verrou accordé. Pour déterminer quand le verrou a été accordé, utilisez la fonction GetOverlappedResult ou l’une des fonctions d’attente. Pour plus d’informations, consultez E/S synchrones et asynchrones.
Si le handle de fichier n’a pas été ouvert pour les E/S asynchrones et que le verrou n’est pas disponible, cet appel attend que le verrou soit accordé ou qu’une erreur se produise, sauf si l’indicateur LOCKFILE_FAIL_IMMEDIATELY est spécifié.
Les verrous exclusifs ne peuvent pas chevaucher une région verrouillée existante d’un fichier. Les verrous partagés peuvent chevaucher une région verrouillée, à condition que les verrous conservés sur cette région soient des verrous partagés. Un verrou partagé peut chevaucher un verrou exclusif si les deux verrous ont été créés à l’aide du même handle de fichier. Lorsqu’un verrou partagé chevauche un verrou exclusif, le seul accès possible est une lecture par le propriétaire des verrous. Si la même plage est verrouillée avec un verrou exclusif et un verrou partagé, deux opérations de déverrouillage sont nécessaires pour déverrouiller la région ; la première opération de déverrouillage déverrouille le verrou exclusif, la deuxième opération de déverrouillage déverrouille le verrou partagé.
Si un processus se termine avec une partie d’un fichier verrouillé ou ferme un fichier qui a des verrous en attente, les verrous sont déverrouillés par le système d’exploitation. Toutefois, le temps nécessaire au système d’exploitation pour déverrouiller ces verrous dépend des ressources système disponibles. Par conséquent, il est recommandé que votre processus déverrouille explicitement tous les fichiers qu’il a verrouillés à l’arrêt. Si cela n’est pas fait, l’accès à ces fichiers peut être refusé si le système d’exploitation ne les a pas encore déverrouillés.
Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.
| Technologie | Prise en charge |
|---|---|
| Protocole Server Message Block (SMB) 3.0 | Oui |
| Basculement transparent SMB 3.0 (TFO) | Oui |
| SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO) | Oui |
| Système de fichiers du volume partagé de cluster (CsvFS) | Oui |
| Système de fichiers résilient (ReFS) | Oui |
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | fileapi.h (inclure Windows.h) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |
Voir aussi
Verrouillage et déverrouillage de plages d’octets dans des fichiers