Função FltSetStreamContext (fltkernel.h)
A rotina FltSetStreamContext define um contexto para um fluxo de arquivos.
Sintaxe
NTSTATUS FLTAPI FltSetStreamContext(
[in] PFLT_INSTANCE Instance,
[in] PFILE_OBJECT FileObject,
[in] FLT_SET_CONTEXT_OPERATION Operation,
[in] PFLT_CONTEXT NewContext,
[out] PFLT_CONTEXT *OldContext
);
Parâmetros
[in] Instance
Um ponteiro de instância opaco para a instância do driver de minifiltro cujo contexto deve ser inserido, removido ou substituído na lista de contextos anexados ao fluxo de arquivos.
[in] FileObject
Um ponteiro para um objeto de arquivo para o fluxo de arquivos.
[in] Operation
Sinalizador especificando detalhes da operação a ser executada. Esse parâmetro deve ser um dos seguintes:
Sinalizador | Significado |
---|---|
FLT_SET_CONTEXT_REPLACE_IF_EXISTS | Se um contexto já estiver definido para Instância, FltSetStreamContext o substituirá pelo contexto especificado em NewContext. Caso contrário, ele inserirá NewContext na lista de contextos para o fluxo de arquivos. |
FLT_SET_CONTEXT_KEEP_IF_EXISTS | Se um contexto já estiver definido para esta Instância, FltSetStreamContext retornará STATUS_FLT_CONTEXT_ALREADY_DEFINED e não substituirá o contexto existente ou incrementará a contagem de referência. Se um contexto ainda não tiver sido definido, a rotina inserirá NewContext na lista de contextos para o fluxo de arquivos e incrementará a contagem de referência. |
[in] NewContext
Um ponteiro para o novo contexto a ser definido para o fluxo de arquivos. Esse parâmetro é necessário e não pode ser NULL.
[out] OldContext
Um ponteiro para uma variável alocada pelo chamador que recebe o endereço do contexto de fluxo existente para o parâmetro Instance , se já estiver definido. Esse parâmetro é opcional e pode ser NULL. Para obter mais informações sobre esse parâmetro, consulte a seção Comentários a seguir.
Retornar valor
A rotina FltSetStreamContext retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:
Código de retorno | Descrição |
---|---|
STATUS_FLT_CONTEXT_ALREADY_DEFINED | Se FLT_SET_CONTEXT_KEEP_IF_EXISTS tiver sido especificado para Operação, esse código de erro indicará que um contexto de fluxo já está anexado ao fluxo de arquivos. |
STATUS_FLT_CONTEXT_ALREADY_LINKED | O contexto apontado pelo parâmetro NewContext já está vinculado a um objeto . Em outras palavras, esse código de erro indica que NewContext já está em uso devido a uma chamada anterior bem-sucedida de uma rotina de ContextoXxx fltSet. |
STATUS_FLT_DELETING_OBJECT | A instância especificada no parâmetro Instance está sendo interrompida. Este é um código de erro. |
STATUS_INVALID_PARAMETER | Um parâmetro inválido foi passado. Por exemplo, o parâmetro NewContext não aponta para um contexto de fluxo válido ou um valor inválido foi especificado para o parâmetro Operation . Este é um código de erro. |
STATUS_NOT_SUPPORTED | O sistema de arquivos não dá suporte a contextos por fluxo para esse fluxo de arquivos. Este é um código de erro. |
Comentários
Para obter mais informações sobre contextos, consulte Sobre contextos de minifiltro.
Um driver de minifiltro chama FltSetStreamContext para anexar um contexto de fluxo a um fluxo de arquivos ou para remover ou substituir um contexto de fluxo existente. Um driver de minifiltro pode anexar um contexto por instância de driver de minifiltro ao fluxo de arquivos.
FltSetStreamContext não pode ser chamado em um FileObject não aberto. Portanto, ele não pode ser chamado de um retorno de chamada de pré-criação para um fluxo porque o fluxo não foi aberto nesse ponto. No entanto, um driver de minifiltro pode alocar e configurar o contexto de fluxo no retorno de chamada de pré-criação, passá-lo para o retorno de chamada pós-criação usando o parâmetro de contexto de conclusão e definir o contexto de fluxo no fluxo no retorno de chamada pós-criação.
Contagem de referências
Se FltSetStreamContext for bem-sucedido:
- A contagem de referência em NewContext é incrementada. Quando NewContext não for mais necessário, o minifiltro deverá chamar FltReleaseContext para diminuir sua contagem de referência.
Caso contrário, se FltSetStreamContext falhar:
- A contagem de referência em NewContext permanece inalterada.
- Se OldContext não for NULL e não apontar para NULL_CONTEXT , OldContext será um ponteiro referenciado para o contexto atualmente associado ao fluxo. O filtro que chama FltSetStreamContext deve chamar FltReleaseContext para OldContext também quando o ponteiro de contexto não for mais necessário.
Independentemente do sucesso:
- O filtro que chama FltSetStreamContext deve chamar FltReleaseContext para diminuir a contagem de referência no objeto NewContext que foi incrementado por FltAllocateContext.
Para obter mais informações, consulte Referenciando contextos.
Outras operações de contexto
Para obter mais informações, consulte Configurando contextos e Liberando contextos:
Para determinar se há suporte para contextos de fluxo para um determinado arquivo, chame FltSupportsStreamContexts
Para alocar um novo contexto, chame FltAllocateContext.
Para obter um contexto de fluxo, chame FltGetStreamContext.
Para excluir um contexto de fluxo, chame FltDeleteStreamContext ou FltDeleteContext.
Requisitos
Requisito | Valor |
---|---|
Cliente mínimo com suporte | Disponível e com suporte no Pacote Cumulativo de Atualizações do Microsoft Windows 2000 1 para SP4, Windows XP SP2, Windows Server 2003 SP1 e sistemas operacionais posteriores. |
Plataforma de Destino | Universal |
Cabeçalho | fltkernel.h (inclua Fltkernel.h) |
Biblioteca | FltMgr.lib |
DLL | Fltmgr.sys |
IRQL | <= APC_LEVEL |