Funzione LockFileEx (fileapi.h)

Articolo
02/26/2024

Blocca il file specificato per l'accesso esclusivo dal processo chiamante. Questa funzione può funzionare in modo sincrono o asincrono e può richiedere un blocco esclusivo o condiviso.

Sintassi

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

Parametri

[in] hFile

Handle per il file. L'handle deve essere stato creato con il diritto di accesso GENERIC_READ o GENERIC_WRITE . Per altre informazioni, vedere Protezione dei file e diritti di accesso.

[in] dwFlags

Questo parametro può essere uno o più dei valori seguenti.

Valore	Significato
LOCKFILE_EXCLUSIVE_LOCK 0x00000002	La funzione richiede un blocco esclusivo. In caso contrario, richiede un blocco condiviso.
LOCKFILE_FAIL_IMMEDIATELY 0x00000001	La funzione restituisce immediatamente se non è in grado di acquisire il blocco richiesto. In caso contrario, attende.

dwReserved

Parametro riservato; deve essere impostato su zero.

[in] nNumberOfBytesToLockLow

32 bit della lunghezza dell'intervallo di byte da bloccare.

[in] nNumberOfBytesToLockHigh

32 bit di ordine elevato della lunghezza dell'intervallo di byte da bloccare.

[in, out] lpOverlapped

Puntatore a una struttura OVERLAPPED utilizzata dalla funzione con la richiesta di blocco. Questa struttura, obbligatoria, contiene l'offset del file all'inizio dell'intervallo di blocchi. È necessario inizializzare il membro hEvent in un handle valido o zero.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero (TRUE).

Se la funzione ha esito negativo, il valore restituito è zero (FALSE). Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Il blocco di un'area di un file viene usato per acquisire l'accesso condiviso o esclusivo all'area specificata usando questo handle di file. Se l'handle di file viene ereditato da un processo creato dal processo di blocco, al processo figlio non viene concesso l'accesso all'area bloccata. Se il processo di blocco apre il file una seconda volta, non può accedere all'area specificata tramite questo secondo handle finché non sblocca l'area.

Il blocco di una parte di un file per l'accesso esclusivo nega a tutti gli altri processi l'accesso in lettura e scrittura all'area specificata del file. Il blocco di un'area che supera la posizione finale del file corrente non è un errore.

Il blocco di una parte di un file per l'accesso condiviso nega l'accesso in scrittura a tutti i processi all'area specificata del file, incluso il processo che blocca prima l'area. Tutti i processi possono leggere l'area bloccata.

Il blocco di un'area di un file non impedisce la lettura o la scrittura da una visualizzazione file mappata.

La funzione LockFileEx funziona in modo asincrono se l'handle di file è stato aperto per l'I/O asincrono, a meno che non venga specificato il flag LOCKFILE_FAIL_IMMEDIATELY . Se viene richiesto un blocco esclusivo per un intervallo di un file che dispone già di un blocco condiviso o esclusivo, la funzione restituisce l'errore ERROR_IO_PENDING. Il sistema segnalerà l'evento specificato nella struttura OVERLAPPED dopo la concessione del blocco. Per determinare quando è stato concesso il blocco, usare la funzione GetOverlappedResult o una delle funzioni di attesa. Per altre informazioni, vedere I/O sincrono e asincrono.

Se l'handle di file non è stato aperto per operazioni di I/O asincrone e il blocco non è disponibile, questa chiamata attende fino a quando non viene concesso il blocco o si verifica un errore, a meno che non venga specificato il flag LOCKFILE_FAIL_IMMEDIATELY .

I blocchi esclusivi non possono sovrapporsi a un'area bloccata esistente di un file. I blocchi condivisi possono sovrapporsi a un'area bloccata, i blocchi mantenuti in tale area sono blocchi condivisi. Un blocco condiviso può sovrapporsi a un blocco esclusivo se entrambi i blocchi sono stati creati usando lo stesso handle di file. Quando un blocco condiviso si sovrappone a un blocco esclusivo, l'unico accesso possibile è una lettura da parte del proprietario dei blocchi. Se lo stesso intervallo è bloccato con un blocco esclusivo e condiviso, sono necessarie due operazioni di sblocco per sbloccare l'area; la prima operazione di sblocco sblocca il blocco esclusivo, la seconda operazione di sblocco sblocca il blocco condiviso.

Se un processo termina con una parte di un file bloccato o chiude un file con blocchi in sospeso, i blocchi vengono sbloccati dal sistema operativo. Tuttavia, il tempo necessario per sbloccare questi blocchi dal sistema operativo dipende dalle risorse di sistema disponibili. Pertanto, è consigliabile che il processo sblocchi in modo esplicito tutti i file che ha bloccato quando termina. Se questa operazione non viene eseguita, l'accesso a questi file potrebbe essere negato se il sistema operativo non li ha ancora sbloccati.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia	Supportato
Protocollo SMB (Server Message Block) 3.0	Sì
Failover trasparente SMB 3.0 (TFO)	Sì
SMB 3.0 con condivisioni file di scalabilità orizzontale (SO)	Sì
File system del volume condiviso cluster (CsvFS)	Sì
Resilient File System (ReFS)	Sì

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	fileapi.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll