Función LockFileEx (fileapi.h)

Artículo
08/23/2023

Bloquea el archivo especificado para el acceso exclusivo por el proceso de llamada. Esta función puede funcionar de forma sincrónica o asincrónica y puede solicitar un bloqueo exclusivo o compartido.

Sintaxis

BOOL LockFileEx(
  [in]      HANDLE       hFile,
  [in]      DWORD        dwFlags,
            DWORD        dwReserved,
  [in]      DWORD        nNumberOfBytesToLockLow,
  [in]      DWORD        nNumberOfBytesToLockHigh,
  [in, out] LPOVERLAPPED lpOverlapped
);

Parámetros

[in] hFile

Identificador del archivo. El identificador debe haberse creado con el derecho de acceso GENERIC_READ o GENERIC_WRITE . Para obtener más información, vea Seguridad de archivos y derechos de acceso.

[in] dwFlags

Este parámetro puede ser uno o varios de los valores siguientes.

Valor	Significado
LOCKFILE_EXCLUSIVE_LOCK 0x00000002	La función solicita un bloqueo exclusivo. De lo contrario, solicita un bloqueo compartido.
LOCKFILE_FAIL_IMMEDIATELY 0x00000001	La función devuelve inmediatamente si no puede adquirir el bloqueo solicitado. De lo contrario, espera.

dwReserved

Parámetro reservado; debe establecerse en cero.

[in] nNumberOfBytesToLockLow

El orden bajo de 32 bits de la longitud del intervalo de bytes que se va a bloquear.

[in] nNumberOfBytesToLockHigh

El orden alto de 32 bits de la longitud del intervalo de bytes que se va a bloquear.

[in, out] lpOverlapped

Puntero a una estructura SUPERPUESTA que la función usa con la solicitud de bloqueo. Esta estructura, que es necesaria, contiene el desplazamiento de archivo del principio del intervalo de bloqueo. Debe inicializar el miembro hEvent en un identificador válido o cero.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es distinto de cero (TRUE).

Si se produce un error en la función, el valor devuelto es cero (FALSE). Para obtener información de error extendida, llame a GetLastError.

Comentarios

El bloqueo de una región de un archivo se usa para adquirir acceso compartido o exclusivo a la región especificada mediante este identificador de archivo. Si un proceso creado por el proceso de bloqueo hereda el identificador de archivo, el proceso secundario no tiene acceso a la región bloqueada. Si el proceso de bloqueo abre el archivo una segunda vez, no podrá acceder a la región especificada a través de este segundo identificador hasta que desbloquee la región.

El bloqueo de una parte de un archivo para el acceso exclusivo deniega a todos los demás procesos acceso de lectura y escritura a la región especificada del archivo. El bloqueo de una región que va más allá de la posición actual del final del archivo no es un error.

Bloquear una parte de un archivo para el acceso compartido deniega a todos los procesos acceso de escritura a la región especificada del archivo, incluido el proceso que bloquea primero la región. Todos los procesos pueden leer la región bloqueada.

El bloqueo de una región de un archivo no impide leer o escribir desde una vista de archivo asignada.

La función LockFileEx funciona de forma asincrónica si el identificador de archivo se abrió para E/S asincrónica, a menos que se especifique la marca de LOCKFILE_FAIL_IMMEDIATELY . Si se solicita un bloqueo exclusivo para un intervalo de un archivo que ya tiene un bloqueo compartido o exclusivo, la función devuelve el error ERROR_IO_PENDING. El sistema indicará el evento especificado en la estructura SUPERPUESTA después de conceder el bloqueo. Para determinar cuándo se ha concedido el bloqueo, use la función GetOverlappedResult o una de las funciones de espera. Para obtener más información, consulte E /S sincrónica y asincrónica.

Si el identificador de archivo no se abrió para E/S asincrónica y el bloqueo no está disponible, esta llamada espera hasta que se conceda el bloqueo o se produzca un error, a menos que se especifique la marca de LOCKFILE_FAIL_IMMEDIATELY .

Los bloqueos exclusivos no se pueden superponer a una región bloqueada existente de un archivo. Los bloqueos compartidos pueden superponerse a una región bloqueada proporcionada por los bloqueos que se mantienen en esa región son bloqueos compartidos. Un bloqueo compartido puede superponerse a un bloqueo exclusivo si ambos bloqueos se crearon con el mismo identificador de archivo. Cuando un bloqueo compartido se superpone a un bloqueo exclusivo, el único acceso posible es leído por el propietario de los bloqueos. Si el mismo intervalo está bloqueado con un bloqueo exclusivo y compartido, se necesitan dos operaciones de desbloqueo para desbloquear la región; la primera operación de desbloqueo desbloquea el bloqueo exclusivo, la segunda operación de desbloqueo desbloquea el bloqueo compartido.

Si un proceso finaliza con una parte de un archivo bloqueado o cierra un archivo que tiene bloqueos pendientes, el sistema operativo desbloquea los bloqueos. Sin embargo, el tiempo necesario para que el sistema operativo desbloquee estos bloqueos depende de los recursos del sistema disponibles. Por lo tanto, se recomienda que el proceso desbloquee explícitamente todos los archivos que ha bloqueado cuando finaliza. Si esto no se hace, es posible que se deniegue el acceso a estos archivos si el sistema operativo aún no los ha desbloqueado.

En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.

Tecnología	Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	Sí
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Sí
Sistema de archivos de Volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente a errores (ReFS)	Sí

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	fileapi.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll