Função FltSetFileContext (fltkernel.h)
A rotina FltSetFileContext define um contexto para um arquivo.
Sintaxe
NTSTATUS FLTAPI FltSetFileContext(
[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 opaco para uma instância de driver de minifiltro para o chamador. Esse parâmetro é necessário e não pode ser NULL.
[in] FileObject
Ponteiro para um objeto de arquivo para o arquivo. Esse parâmetro é necessário e não pode ser NULL.
[in] Operation
Um sinalizador que especifica o tipo de operação a ser executada por FltSetFileContext . Esse parâmetro deve ser um dos seguintes sinalizadores:
| Sinalizador | Significado |
|---|---|
| FLT_SET_CONTEXT_REPLACE_IF_EXISTS | Se um contexto já estiver definido para o arquivo para o qual o parâmetro FileObject aponta, FltSetFileContext substituirá esse contexto pelo contexto especificado em NewContext. Caso contrário, ele inserirá NewContext na lista de contextos do arquivo. |
| FLT_SET_CONTEXT_KEEP_IF_EXISTS | Se um contexto já estiver definido para o arquivo para o qual FileObject aponta, FltSetFileContext retornará STATUS_FLT_CONTEXT_ALREADY_DEFINED e não substituirá o contexto existente nem incrementará a contagem de referência. Se um contexto ainda não tiver sido definido, a rotina inserirá o contexto especificado em NewContext na lista de contextos para o arquivo e incrementará a contagem de referência. |
[in] NewContext
Um ponteiro para o novo contexto a ser definido para o arquivo. 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 arquivo existente para a instância apontada pelo parâmetro Instance , se já estiver definida. 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 FltSetFileContext 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 foi especificado para o parâmetro Operation , esse código de erro indica que um contexto já está anexado ao arquivo. |
| 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 arquivo válido ou um valor inválido foi especificado para o parâmetro Operation . Este é um código de erro. |
| STATUS_NOT_SUPPORTED | Não há suporte para contextos de arquivo para este arquivo. 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 FltSetFileContext para definir ou substituir seu próprio contexto de arquivo em um arquivo. Um driver de minifiltro pode anexar apenas um contexto por instância de driver de minifiltro ao arquivo.
FltSetFileContext não pode ser chamado em um FileObject não aberto. Portanto, FltSetFileContext não pode ser chamado de um retorno de chamada de pré-criação para um arquivo porque o arquivo não foi aberto nesse momento. No entanto, um driver de minifiltro pode alocar e configurar o contexto do arquivo 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 arquivo no arquivo correspondente a esse fluxo no retorno de chamada pós-criação.
Contagem de referências
Se FltSetFileContext for bem-sucedido:
- A contagem de referência em NewContext é incrementada. Quando NewContext não é mais necessário, o minifiltro deve chamar FltReleaseContext para diminuir sua contagem de referência.
Caso contrário, se FltSetFileContext 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 arquivo. O filtro que chama FltSetFileContext deve eventualmente chamar FltReleaseContext para OldContext também quando o ponteiro de contexto não for mais necessário.
Independentemente do sucesso:
- O filtro que chama FltSetFileContext deve chamar FltReleaseContext para decrementar 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 Definindo contextos e Liberando contextos:
Para alocar um novo contexto, chame FltAllocateContext.
Para obter um contexto de arquivo, chame FltGetFileContext.
Para excluir um contexto de arquivo, chame FltDeleteFileContext ou FltDeleteContext.
Para determinar se há suporte para contextos de arquivo para um determinado arquivo, chame FltSupportsFileContexts ou FltSupportsFileContextsEx.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível e com suporte a partir do Windows Vista. |
| Plataforma de Destino | Universal |
| Cabeçalho | fltkernel.h (inclua Fltkernel.h) |
| Biblioteca | Fltmgr.lib |
| DLL | Fltmgr.sys |
| IRQL | <= APC_LEVEL |