Partilhar via

FSCTL_REQUEST_OPLOCK IOCTL (winioctl.h)

  • Artigo

Solicita um bloqueio oportunista (oplock) em um arquivo e reconhece que ocorreu uma quebra de oplock.

Para executar essa operação, chame a função DeviceIoControl usando os parâmetros a seguir.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                 // handle to file
  FSCTL_REQUEST_OPLOCK,             // dwIoControlCode
  (LPVOID) lpInBuffer,              // pointer to REQUEST_OPLOCK_INPUT_BUFFER
  (DWORD) nInBufferSize,            // size of input buffer
  (LPVOID) lpOutBuffer,             // pointer to REQUEST_OPLOCK_OUTPUT_BUFFER
  (DWORD) nOutBufferSize,           // size of output buffer
  NULL,                             // number of bytes returned
  (LPOVERLAPPED) lpOverlapped       // OVERLAPPED structure
);

Observações

Essa operação é usada por aplicativos cliente para solicitar um bloqueio oportunista (oplock) de um servidor local. Os aplicativos cliente não devem solicitar bloqueios oportunistas diretamente de servidores remotos — o redirecionador de rede solicita de forma transparente bloqueios oportunistas para o aplicativo. Usar essa operação para solicitar bloqueios oportunistas de servidores remotos resultará na negação da solicitação.

Se a operação DeviceIoControl retornar o código de erro ERROR_IO_PENDING, a solicitação oplock será concedida. Se ele retornar qualquer outro código de erro, o oplock não foi concedido. Se o código de erro for um valor de aviso, como ERROR_CANNOT_GRANT_REQUESTED_OPLOCK, as informações estendidas poderão estar disponíveis na estrutura REQUEST_OPLOCK_OUTPUT_BUFFER.

Quando um oplock concedido for interrompido, o objeto de evento na estrutura deOVERLAPPED será sinalizado e as informações serão retornadas na estrutura REQUEST_OPLOCK_OUTPUT_BUFFER. O membro de interno da estrutura de OVERLAPPED será definido como um valor NTSTATUS que fornece informações estendidas sobre como o oplock foi quebrado.

SOBREPOSTA. Valor interno Significado
STATUS_SUCCESS
0x0		 O oplock foi quebrado por outra operação do sistema de arquivos.
STATUS_OPLOCK_HANDLE_CLOSED
0x00000216		 O oplock não está mais em vigor porque o identificador de arquivo usado para solicitá-lo foi fechado. Observe que, se um oplock for interrompido porque o identificador usado para solicitá-lo foi fechado, não haverá necessidade de reconhecer a interrupção, independentemente do tipo oplock.
STATUS_OPLOCK_SWITCHED_TO_NEW_HANDLE
0x00000215		 O oplock ainda está em vigor, no entanto, ele não está mais associado ao identificador de arquivo que foi usado para solicitá-lo. Um chamador usou um identificador diferente para o arquivo para solicitar um novo oplock, e esse identificador agora possui o oplock.

O código de controle FSCTL_REQUEST_OPLOCK fornece uma funcionalidade mais eficiente do que os seguintes códigos de controle relacionados: FSCTL_REQUEST_OPLOCK_LEVEL_1, FSCTL_REQUEST_OPLOCK_LEVEL_2, FSCTL_REQUEST_FILTER_OPLOCKe FSCTL_REQUEST_BATCH_OPLOCK. A solicitação de diferentes níveis de oplock pode ser executada repetidamente no mesmo identificador sem fechar e reabrir o identificador ao usar FSCTL_REQUEST_OPLOCK; os outros códigos de controle exigem que o identificador seja fechado e reaberto com CreateFile para fazer essa alteração. Isso é feito manipulando o membro requestedOplockLevel da estrutura REQUEST_OPLOCK_INPUT_BUFFER ao emitir novamente o código de controle FSCTL_REQUEST_OPLOCK.

A tabela a seguir resume como a capacidade de cache dos tipos oplock disponíveis de FSCTL_REQUEST_OPLOCK correspondem aos oplocks de nível 2, nível 1 e lote.

Código de controle alternativo Valor de sinalizadores RequestedOplockLevel equivalentes Tipo de Oplock
FSCTL_REQUEST_BATCH_OPLOCK OPLOCK_LEVEL_CACHE_READ \| OPLOCK_LEVEL_CACHE_WRITE \| OPLOCK_LEVEL_CACHE_HANDLE RWH
FSCTL_REQUEST_OPLOCK_LEVEL_1 OPLOCK_LEVEL_CACHE_READ \| OPLOCK_LEVEL_CACHE_WRITE RW
FSCTL_REQUEST_OPLOCK_LEVEL_2 OPLOCK_LEVEL_CACHE_READ R

Usar o código de controle FSCTL_REQUEST_OPLOCK com o membro RequestedOplockLevel definido para OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE concede um oplock do tipo RH. Um oplock RH é semelhante ao oplock de filtro concedido pelo código de controle FSCTL_REQUEST_FILTER_OPLOCK. No entanto, observe que o oplock de filtro permite que apenas um cliente mantenha um oplock em um arquivo de cada vez; FSCTL_REQUEST_OPLOCK permite que vários clientes de cada vez tenham o rh bloqueio em um arquivo. Outra diferença é que FSCTL_REQUEST_FILTER_OPLOCK requer uma confirmação de interrupção de oplock antes que as gravações possam ocorrer, em que FSCTL_REQUEST_OPLOCK não ocorre porque a notificação de interrupção do oplock é somente consultoria e as gravações têm permissão para prosseguir sem confirmação. Para obter mais informações, consulte Breaking Oplocks.

Um código de controle FSCTL_REQUEST_OPLOCK falhará se o arquivo for aberto no modo não sobreposto (síncrono).

Para obter as implicações da E/S sobreposta nesta operação, consulte a seção Comentários do tópico DeviceIoControl.

No Windows 8 e no Windows Server 2012, esse código é compatível com as tecnologias a seguir.

Tecnologia Suportado
Protocolo SMB (Bloco de Mensagens do Servidor) 3.0 Não
TFO (Failover Transparente) do SMB 3.0 Não
SMB 3.0 com Compartilhamentos de Arquivos de Expansão (SO) Não
Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS) Sim
ReFS (Sistema de Arquivos Resiliente) Sim

Além disso, a partir do Windows 8 e do Windows Server 2012, o código de controle FSCTL_REQUEST_OPLOCK pode ser usado para solicitar um oplock em um diretório, bem como em um arquivo. Uma solicitação oplock em um diretório pode especificar OPLOCK_LEVEL_CACHE_READ ou OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE no membro RequestedOplockLevel.

Um oplock R ou RH em um diretório quebra para Nenhum quando o conteúdo de uma enumeração do diretório seria alterado. Por exemplo, adicionar/excluir um arquivo no diretório, alterar o tamanho de um arquivo no diretório, modificar o carimbo de data/hora de um arquivo no diretório, etc., quebraria o oplock no diretório. Essa quebra de oplock não requer uma confirmação antes que as alterações no diretório possam ocorrer; é somente consultoria.

Um oplock RH em um diretório quebra para R quando o próprio diretório é renomeado ou excluído. Essa quebra de oplock requer uma confirmação antes que a alteração no diretório possa ocorrer.

Requisitos

Requisito Valor
de cliente com suporte mínimo Windows 7 [somente aplicativos da área de trabalho]
servidor com suporte mínimo Windows Server 2008 R2 [somente aplicativos da área de trabalho]
cabeçalho winioctl.h (inclua Windows.h)

Consulte também