Funzione LockFileEx (fileapi.h)
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.
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 |