Função IoCancelFileOpen (ntddk.h)

Artigo
08/07/2023

A rotina IoCancelFileOpen pode ser usada por um driver de filtro do sistema de arquivos para fechar um arquivo que foi aberto por um driver do sistema de arquivos na pilha de dispositivos do driver de filtro.

Sintaxe

void IoCancelFileOpen(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PFILE_OBJECT   FileObject
);

Parâmetros

[in] DeviceObject

Ponteiro para a parte superior da pilha do dispositivo imediatamente abaixo do objeto de dispositivo do driver de filtro.

[in] FileObject

Ponteiro para o objeto de arquivo para o arquivo a ser fechado.

Retornar valor

Nenhum

Comentários

Se um driver de filtro do sistema de arquivos determinar que uma solicitação de abertura de arquivo ou criação de arquivo deve falhar depois que os drivers de nível inferior já tiverem concluído a solicitação com STATUS_SUCCESS, ele poderá usar IoCancelFileOpen para fechar o arquivo aberto pelos drivers de nível inferior.

Embora STATUS_REPARSE seja um valor NTSTATUS bem-sucedido, não é necessário chamar IoCancelFileOpen para uma operação de criação que foi concluída com STATUS_REPARSE, pois esse valor status indica que o arquivo não foi aberto com êxito.

Uma chamada bem-sucedida para IoCancelFileOpen tem o seguinte efeito: Para minifiltros e filtros herdados que estão acima do chamador na pilha do sistema de arquivos, a solicitação de criação parece ter falhado. Para aqueles que estão abaixo do chamador, o arquivo parece ter sido aberto (ou criado) e, em seguida, fechado.

Observe que IoCancelFileOpen não desfaz nenhuma modificação no arquivo. Por exemplo, IoCancelFileOpen não exclui um arquivo recém-criado nem restaura um arquivo que foi substituído ou substituído por seu estado anterior.

Um exemplo típico é o seguinte:

Existe um driver de filtro entre um driver de filtro de nível superior e um driver de sistema de arquivos de nível inferior.
O driver de filtro passa uma solicitação IRP_MJ_CREATE na pilha do dispositivo para o driver do sistema de arquivos e o driver do sistema de arquivos conclui a solicitação IRP_MJ_CREATE com status STATUS_SUCCESS.
Antes que o driver de filtro conclua a solicitação de criação, ele determina que o arquivo deve ser fechado.
O driver de filtro usa IoCancelFileOpen para fechar o arquivo que foi aberto pelo driver do sistema de arquivos.

Depois de chamar IoCancelFileOpen, o driver de filtro deve concluir a solicitação de criação com um código de erro apropriado, como STATUS_UNSUCCESSFUL ou STATUS_ACCESS_DENIED. Além disso, ele deve definir o campo Irp-IoStatus.Information> como zero.

IoCancelFileOpen deve ser chamado antes que todos os identificadores sejam criados para o arquivo. Os chamadores podem marcar o membro Flags da estrutura FILE_OBJECT para a qual o parâmetro FileObject aponta. Se o sinalizador FO_HANDLE_CREATED estiver definido, isso significa que um ou mais identificadores foram criados para o arquivo, portanto, não é seguro chamar IoCancelFileOpen.

IoCancelFileOpen define o sinalizador FO_FILE_OPEN_CANCELLED no membro Flags do objeto de arquivo para o qual FileObject aponta. Esse sinalizador indica que a solicitação IRP_MJ_CREATE foi cancelada e uma solicitação de IRP_MJ_CLOSE será emitida para esse objeto de arquivo. Depois que a operação de criação tiver sido cancelada, ela não poderá ser reempresada, ou seja, STATUS_REPARSE não poderá ser retornada pelo driver de filtro herdado se tiver chamado a rotina IoCreateFileOpen .

Os minifilters devem usar FltCancelFileOpen em vez de IoCancelFileOpen.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Essa rotina está disponível no Microsoft Windows 2000 e posterior.
Plataforma de Destino	Universal
Cabeçalho	ntddk.h (inclua Ntddk.h, Ntifs.h, Fltkernel.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL