LockFileEx, fonction (fileapi.h)

Article
08/23/2023

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.

Valeur	Signification
LOCKFILE_EXCLUSIVE_LOCK 0x00000002	La fonction demande un verrou exclusif. Sinon, il demande un verrou partagé.
LOCKFILE_FAIL_IMMEDIATELY 0x00000001	La fonction retourne immédiatement si elle ne parvient pas à acquérir le verrou demandé. Sinon, il attend.

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