Função LockFileEx (fileapi.h)
Bloqueia o arquivo especificado para acesso exclusivo pelo processo de chamada. Essa função pode operar de forma síncrona ou assíncrona e pode solicitar um bloqueio exclusivo ou compartilhado.
Sintaxe
BOOL LockFileEx(
[in] HANDLE hFile,
[in] DWORD dwFlags,
DWORD dwReserved,
[in] DWORD nNumberOfBytesToLockLow,
[in] DWORD nNumberOfBytesToLockHigh,
[in, out] LPOVERLAPPED lpOverlapped
);
Parâmetros
[in] hFile
Um identificador para o arquivo. O identificador deve ter sido criado com o GENERIC_READ ou GENERIC_WRITE direito de acesso. Para obter mais informações, consulte Segurança de Arquivos e Direitos de Acesso.
[in] dwFlags
Esse parâmetro pode ser um ou mais dos seguintes valores.
dwReserved
Parâmetro reservado; deve ser definido como zero.
[in] nNumberOfBytesToLockLow
Os 32 bits de ordem baixa do comprimento do intervalo de bytes a serem bloqueados.
[in] nNumberOfBytesToLockHigh
Os 32 bits de ordem alta do comprimento do intervalo de bytes a serem bloqueados.
[in, out] lpOverlapped
Um ponteiro para uma estrutura OVERLAPPED que a função usa com a solicitação de bloqueio. Essa estrutura, que é necessária, contém o deslocamento de arquivo do início do intervalo de bloqueio. Você deve inicializar o membro hEvent para um identificador válido ou zero.
Retornar valor
Se a função for bem-sucedida, o valor retornado será não zero (TRUE).
Se a função falhar, o valor retornado será zero (FALSE). Para obter informações de erro estendidas, chame GetLastError.
Comentários
O bloqueio de uma região de um arquivo é usado para adquirir acesso compartilhado ou exclusivo à região especificada usando esse identificador de arquivo. Se o identificador de arquivo for herdado por um processo criado pelo processo de bloqueio, o processo filho não receberá acesso à região bloqueada. Se o processo de bloqueio abrir o arquivo uma segunda vez, ele não poderá acessar a região especificada por meio desse segundo identificador até desbloquear a região.
Bloquear uma parte de um arquivo para acesso exclusivo nega todos os outros processos de acesso de leitura e gravação à região especificada do arquivo. Bloquear uma região que vai além da posição atual do fim do arquivo não é um erro.
Bloquear uma parte de um arquivo para acesso compartilhado nega que todos os processos gravam acesso à região especificada do arquivo, incluindo o processo que primeiro bloqueia a região. Todos os processos podem ler a região bloqueada.
Bloquear uma região de um arquivo não impede a leitura ou gravação de uma exibição de arquivo mapeada.
A função LockFileEx funcionará de forma assíncrona se o identificador de arquivo foi aberto para E/S assíncrona, a menos que o sinalizador LOCKFILE_FAIL_IMMEDIATELY seja especificado. Se um bloqueio exclusivo for solicitado para um intervalo de um arquivo que já tenha um bloqueio compartilhado ou exclusivo, a função retornará o erro ERROR_IO_PENDING. O sistema sinalizará o evento especificado na estrutura OVERLAPPED após a concessão do bloqueio. Para determinar quando o bloqueio foi concedido, use a função GetOverlappedResult ou uma das funções de espera. Para obter mais informações, consulte E/S síncrona e assíncrona.
Se o identificador de arquivo não tiver sido aberto para E/S assíncrona e o bloqueio não estiver disponível, essa chamada aguardará até que o bloqueio seja concedido ou ocorra um erro, a menos que o sinalizador LOCKFILE_FAIL_IMMEDIATELY seja especificado.
Os bloqueios exclusivos não podem se sobrepor a uma região bloqueada existente de um arquivo. Os bloqueios compartilhados podem se sobrepor a uma região bloqueada, desde que os bloqueios mantidos nessa região sejam bloqueios compartilhados. Um bloqueio compartilhado poderá se sobrepor a um bloqueio exclusivo se ambos os bloqueios forem criados usando o mesmo identificador de arquivo. Quando um bloqueio compartilhado se sobrepõe a um bloqueio exclusivo, o único acesso possível é uma leitura pelo proprietário dos bloqueios. Se o mesmo intervalo estiver bloqueado com um bloqueio exclusivo e compartilhado, duas operações de desbloqueio serão necessárias para desbloquear a região; a primeira operação de desbloqueio desbloqueia o bloqueio exclusivo, a segunda operação de desbloqueio desbloqueia o bloqueio compartilhado.
Se um processo for encerrado com uma parte de um arquivo bloqueado ou fechar um arquivo com bloqueios pendentes, os bloqueios serão desbloqueados pelo sistema operacional. No entanto, o tempo necessário para o sistema operacional desbloquear esses bloqueios depende dos recursos disponíveis do sistema. Portanto, é recomendável que o processo desbloqueie explicitamente todos os arquivos bloqueados quando ele for encerrado. Se isso não for feito, o acesso a esses arquivos poderá ser negado se o sistema operacional ainda não os desbloqueou.
Em Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.
Tecnologia | Com suporte |
---|---|
Protocolo SMB (Bloco de Mensagens do Servidor) 3.0 | Yes |
TFO (Failover Transparente) SMB 3.0 | Yes |
SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | Yes |
Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS) | Yes |
ReFS (Sistema de Arquivos Resiliente) | Yes |
Requisitos
Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
Plataforma de Destino | Windows |
Cabeçalho | fileapi.h (inclua Windows.h) |
Biblioteca | Kernel32.lib |
DLL | Kernel32.dll |
Confira também
Bloquear e desbloquear intervalos de bytes em arquivos