Funzione FltSetFileContext (fltkernel.h)

  • Articolo

La routine FltSetFileContext imposta un contesto per un file.

Sintassi

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
);

Parametri

[in] Instance

Puntatore opaco a un'istanza del driver minifilter per il chiamante. Questo parametro è obbligatorio e non può essere NULL.

[in] FileObject

Puntatore a un oggetto file per il file. Questo parametro è obbligatorio e non può essere NULL.

[in] Operation

Flag che specifica il tipo di operazione da eseguire per FltSetFileContext . Questo parametro deve essere uno dei flag seguenti:

Contrassegno Significato
FLT_SET_CONTEXT_REPLACE_IF_EXISTS Se un contesto è già impostato per il file a cui punta il parametro FileObject , FltSetFileContext sostituirà tale contesto con il contesto specificato in NewContext. In caso contrario, verrà inserito NewContext nell'elenco di contesti per il file.
FLT_SET_CONTEXT_KEEP_IF_EXISTS Se un contesto è già impostato per il file a cui fa riferimento FileObject , FltSetFileContext restituirà STATUS_FLT_CONTEXT_ALREADY_DEFINED e non sostituirà il contesto esistente o incrementerà il conteggio dei riferimenti. Se un contesto non è già stato impostato, la routine inserisce il contesto specificato in NewContext nell'elenco dei contesti per il file e incrementa il conteggio dei riferimenti.

[in] NewContext

Puntatore al nuovo contesto da impostare per il file. Questo parametro è obbligatorio e non può essere NULL.

[out] OldContext

Puntatore a una variabile allocata dal chiamante che riceve l'indirizzo del contesto di file esistente per l'istanza a cui punta il parametro Instance , se ne è già impostato uno. Questo parametro è facoltativo e può essere NULL. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguenti.

Valore restituito

La routine FltSetFileContext restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito Descrizione
STATUS_FLT_CONTEXT_ALREADY_DEFINED Se FLT_SET_CONTEXT_KEEP_IF_EXISTS è stato specificato per il parametro Operation , questo codice di errore indica che un contesto è già collegato al file.
STATUS_FLT_CONTEXT_ALREADY_LINKED Il contesto a cui fa riferimento il parametro NewContext è già collegato a un oggetto. In altre parole, questo codice di errore indica che NewContext è già in uso a causa di una chiamata precedente di una routine FltSetXxxContext .
STATUS_FLT_DELETING_OBJECT L'istanza specificata nel parametro Instance viene disattivata. Si tratta di un codice di errore.
STATUS_INVALID_PARAMETER È stato passato un parametro non valido. Ad esempio, il parametro NewContext non punta a un contesto di file valido o un valore non valido è stato specificato per il parametro Operation . Si tratta di un codice di errore.
STATUS_NOT_SUPPORTED I contesti di file non sono supportati per questo file. Si tratta di un codice di errore.

Commenti

Per altre informazioni sui contesti, vedere Informazioni sui contesti minifilter.

Un driver minifilter chiama FltSetFileContext per impostare o sostituire il proprio contesto di file in un file. Un driver minifilter può collegare un solo contesto per istanza del driver minifilter al file.

Impossibile chiamare FltSetFileContext in un FileObject non aperto. Di conseguenza , FltSetFileContext non può essere chiamato da un callback pre-create per un file perché il file non è stato aperto a quel punto. Un driver minifilter può tuttavia allocare e configurare il contesto del file nel callback di pre-creazione, passarlo al callback post-create usando il parametro di contesto di completamento e impostare il contesto del file sul file corrispondente a tale flusso nel callback post-create.

Conteggio dei riferimenti

Se FltSetFileContext ha esito positivo:

  • Il conteggio dei riferimenti su NewContext viene incrementato. Quando NewContext non è più necessario, il minifilter deve chiamare FltReleaseContext per decrererne il conteggio dei riferimenti.

Altrimenti se FltSetFileContext ha esito negativo:

  • Il conteggio dei riferimenti su NewContext rimane invariato.
  • Se OldContext non è NULL e non punta a NULL_CONTEXT , OldContext è un puntatore a riferimento al contesto attualmente associato al file. Il filtro che chiama FltSetFileContext deve chiamare infine FltReleaseContext per OldContext e quando il puntatore del contesto non è più necessario.

Indipendentemente dal successo:

  • Il filtro che chiama FltSetFileContext deve chiamare FltReleaseContext per decrerere il conteggio dei riferimenti nell'oggetto NewContext incrementato da FltAllocateContext.

Per altre informazioni, vedere Riferimenti ai contesti.

Altre operazioni di contesto

Per altre informazioni, vedere Impostazione di contesti e rilascio di contesti:

Requisiti

Requisito Valore
Client minimo supportato Disponibile e supportato a partire da Windows Vista.
Piattaforma di destinazione Universale
Intestazione fltkernel.h (includere Fltkernel.h)
Libreria Fltmgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

Vedi anche

FLT_CONTEXT_REGISTRATION

FltAllocateContext

FltDeleteContext

FltDeleteFileContext

FltGetFileContext

FltReleaseContext

FltSupportsFileContexts

FltSupportsFileContextsEx