Função FsRtlRemovePerStreamContext (ntifs.h)

Artigo
12/21/2024

FsRtlRemovePerStreamContext remove uma estrutura de contexto por fluxo da lista de contextos por fluxo associados a um fluxo de arquivos.

Sintaxe

PFSRTL_PER_STREAM_CONTEXT FsRtlRemovePerStreamContext(
  [in]           PFSRTL_ADVANCED_FCB_HEADER StreamContext,
  [in, optional] PVOID                      OwnerId,
  [in, optional] PVOID                      InstanceId
);

Parâmetros

[in] StreamContext

Ponteiro para a estrutura de FSRTL_ADVANCED_FCB_HEADER do fluxo de arquivos. Para obter esse ponteiro de um objeto de arquivo, use a macro FsRtlGetPerStreamContextPointer.

[in, optional] OwnerId

Usado para identificar informações de contexto como pertencentes a um driver de filtro específico.

[in, optional] InstanceId

Usado para pesquisar uma instância específica de um contexto por fluxo. Se não for fornecido, qualquer um dos contextos pertencentes ao driver de filtro será removido e retornado.

Se o OwnerId nem o InstanceId for fornecido, qualquer contexto por fluxo associado será removido e retornado.

Valor de retorno

FsRtlRemovePerStreamContext retorna um ponteiro para o contexto por fluxo removido. Se nenhuma correspondência for encontrada ou se o sistema de arquivos não oferecer suporte a contextos de filtro, FsRtlRemovePerStreamContext retornará NULL.

Observações

Um driver de filtro do sistema de arquivos chama FsRtlRemovePerStreamContext para remover sua própria estrutura de contexto por fluxo da lista de contextos por fluxo associados a um fluxo de arquivos.

FsRtlRemovePerStreamContext remove apenas a primeira estrutura de contexto correspondente por fluxo encontrada. Se houver contextos de correspondência adicionais por fluxo, o driver de filtro deverá chamar FsRtlRemovePerStreamContext quantas vezes forem necessárias para removê-los todos.

Essa rotina só deve ser usada quando um driver de filtro precisa descartar as informações de contexto associadas a um fluxo de arquivos enquanto o fluxo ainda está aberto. Por exemplo, um driver de filtro pode chamar FsRtlRemovePerStreamContext nos seguintes casos:

Quando ele recebe uma solicitação de um aplicativo no modo de usuário para interromper o registro em log de solicitações de E/S em um volume específico.
Quando detecta que um arquivo ou diretório foi renomeado.

Quando um fluxo de arquivos é fechado, o sistema de arquivos é responsável por garantir que todos os contextos por fluxo associados a esse fluxo sejam removidos e liberados. Para fazer isso, o sistema de arquivos deve chamar FsRtlTeardownPerStreamContexts no FCB (bloco de controle de arquivo) ou outro objeto de contexto de fluxo para o fluxo de arquivos. FsRtlTeardownPerStreamContexts percorre a lista FilterContexts, removendo cada entrada e chamando sua rotina de FreeCallback.

Portanto, um driver de filtro do sistema de arquivos não deve chamar FsRtlRemovePerStreamContext de dentro de uma rotina de expedição IRP_MJ_CLOSE ou IRP_MJ_PNP. Essa chamada não só seria desnecessária, mas também poderia interferir na chamada do sistema de arquivos para FsRtlTeardownPerStreamContexts.

Um driver de filtro do sistema de arquivos não deve chamar FsRtlRemovePerStreamContext de dentro da rotina freecallback de uma estrutura de contexto por fluxo. Isso ocorre porque o sistema de arquivos subjacente chama a rotina FreeCallback depois de já ter removido a estrutura de contexto da lista FilterContexts.

Para inicializar uma estrutura de contexto por fluxo, use a macro FsRtlInitPerStreamContext.

Para associar uma estrutura de contexto inicializada por fluxo a um fluxo de arquivos, chame FsRtlInsertPerStreamContext.

Para recuperar uma estrutura de contexto por fluxo associada a um fluxo de arquivos, chame FsRtlLookupPerStreamContext.

FsRtlRemovePerStreamContext só pode ser usado em sistemas de arquivos que dão suporte a contextos de filtro.

Para obter mais informações, consulte controle Per-Stream contexto em um driver de filtro do sistema de arquivos herdado.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Pacote cumulativo de atualizações do Windows 2000 SP4; Windows XP
da Plataforma de Destino	Universal
cabeçalho	ntifs.h (inclua Ntifs.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL