Função FsRtlOplockFsctrl (ntifs.h)

Artigo
03/01/2024

FsRtlOplockFsctrl executa várias operações oportunistas de bloqueio (oplock) em nome de um sistema de arquivos ou driver de filtro.

Sintaxe

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

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.

Retornar valor

FsRtlOplockFsctrl retorna um dos seguintes valores NTSTATUS:

Código de retorno	Descrição
STATUS_SUCCESS	Para uma solicitação de 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 era 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 êxito.
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 create options para a operação. STATUS_CANNOT_BREAK_OPLOCK é um código de êxito.

Comentários

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

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, FsRtlOplockFsctrl poderá ser usado com um dos seguintes códigos FSCTL, que é definido em IrpSp-Parameters.FileSystemControl.FsControlCode>:

Para obter informações detalhadas 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 , FsRtlOplockFsctrl 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, FsRtlOplockFsctrl 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 com o pacote oplock fornecido pelo sistema. Confira Sincronização do Oplock para obter mais informações.