Função FsRtlOplockFsctrlEx (ntifs.h)

Artigo
02/27/2024

A rotina FsRtlOplockFsctrlEx executa várias operações de bloqueio oportunista (oplock) em nome de um sistema de arquivos ou driver de filtro.

Sintaxe

NTSTATUS FsRtlOplockFsctrlEx(
  [in] POPLOCK Oplock,
  [in] PIRP    Irp,
  [in] ULONG   OpenCount,
  [in] ULONG   Flags
);

Parâmetros

[in] Oplock

Ponteiro oplock oplock opaco para o arquivo. Esse ponteiro deve ter sido inicializado por uma chamada anterior para FsRtlInitializeOplock.

[in] Irp

Ponteiro para o IRP para a operação de E/S. Esse parâmetro é necessário e não pode ser NULL.

[in] OpenCount

Número de identificadores de usuário para o arquivo, se um oplock exclusivo estiver sendo solicitado. Definir um valor diferente de zero para uma solicitação oplock de nível 2, R ou RH indica que há bloqueios de intervalo de bytes no arquivo. Para obter informações sobre tipos oplock, consulte Visão geral do Oplock.

[in] Flags

Uma máscara de bits para as operações oplock associadas. Um sistema de arquivos ou driver de filtro define bits para especificar o comportamento de FsRtlOplockFsctrlEx. Esse parâmetro tem as seguintes opções:

Bandeira	Significado
OPLOCK_FSCTRL_FLAG_ALL_KEYS_MATCH (0x00000001)	O sistema de arquivos verificou que todas as chaves oplock em qualquer identificador aberto no momento correspondem. Ao especificar esse sinalizador, você permite que o pacote oplock conceda um oplock de nível RW ou RWH quando houver mais de um identificador aberto para o arquivo. Para obter mais informações sobre tipos oplock, consulte Visão geral do Oplock.

Valor de retorno

FsRtlOplockFsctrlEx retorna um dos seguintes valores NTSTATUS:

Código de retorno	Descrição
STATUS_SUCCESS	Para uma solicitação IRP_MJ_CREATE, STATUS_SUCCESS indica que o oplock de filtro solicitado foi concedido. Para uma operação FSCTL, o significado de STATUS_SUCCESS depende do código FSCTL. Para obter mais informações, consulte as páginas de referência para os códigos FSCTL listados na seção Comentários a seguir.
STATUS_CANCELLED	A operação de E/S foi cancelada. STATUS_CANCELLED é um código de erro.
STATUS_INVALID_PARAMETER	O código FSCTL para a operação de E/S não foi um dos valores válidos listados na seção Comentários a seguir. STATUS_INVALID_PARAMETER é um código de erro.
STATUS_OPLOCK_NOT_GRANTED	Não foi possível conceder o oplock. STATUS_OPLOCK_NOT_GRANTED é um código de erro.
STATUS_PENDING	Usado somente para operações FSCTL. O significado de STATUS_PENDING depende do código FSCTL. Para obter mais informações, consulte as páginas de referência para os códigos FSCTL listados na seção Comentários a seguir. STATUS_PENDING é um código de sucesso.
STATUS_CANNOT_BREAK_OPLOCK	Não foi possível conceder um novo oplock. O IRP é uma solicitação IRP_MJ_CREATE e FILE_OPEN_REQUIRING_OPLOCK foi especificado no parâmetro de opções de criação para a operação. STATUS_CANNOT_BREAK_OPLOCK é um código de sucesso.

Observações

Sistemas de arquivos e drivers de filtro herdados chamam FsRtlOplockFsctrlEx para executar várias operações oplock para uma operação de E/S de controle do sistema de arquivos ou criação. Os minifiltros devem chamar FltOplockFsctrlEx em vez de FsRtlOplockFsctrlEx.

O IRP apontado pelo parâmetro irp deve ser um IRP válido para uma operação de IRP_MJ_FILE_SYSTEM_CONTROL ou IRP_MJ_CREATE.

Se o IRP for uma solicitação IRP_MJ_FILE_SYSTEM_CONTROL, FsRtlOplockFsctrlEx poderá ser usado com um dos seguintes códigos FSCTL, que é definido em IrpSp->Parameters.FileSystemControl.FsControlCode:

Para obter mais informações sobre essas FSCTLs e sobre bloqueios oportunistas em geral, consulte a documentação do SDK do Microsoft Windows.

Se o IRP for uma solicitação IRP_MJ_CREATE, FsRtlOplockFsctrlEx poderá ser usado para solicitar um oplock de filtro pendente se todas as seguintes condições forem verdadeiras:

O valor do parâmetro OpenCount deve ser 1.
O valor do parâmetro DesiredAccess para a solicitação IRP_MJ_CREATE deve ser FILE_READ_ATTRIBUTES.
O valor do parâmetro ShareAccess para a solicitação IRP_MJ_CREATE deve ser FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

Se a solicitação de um oplock de filtro pendente for concedida, FsRtlOplockFsctrlEx retornará STATUS_SUCCESS. Para obter mais informações sobre como criar parâmetros, consulte a entrada de referência para IRP_MJ_CREATE.

Filtros e sistemas de arquivos que chamam essa função devem sincronizar chamadas no pacote oplock fornecido pelo sistema. Consulte de sincronização oplock para obter mais informações.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	A rotina FsRtlOplockFsctrlEx está disponível a partir do Windows 7.
da Plataforma de Destino	Universal
cabeçalho	ntifs.h (inclua Ntifs.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL