Funzione FltSetFileContext (fltkernel.h)
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:
Per allocare un nuovo contesto, chiamare FltAllocateContext.
Per ottenere un contesto di file, chiamare FltGetFileContext.
Per eliminare un contesto di file, chiamare FltDeleteFileContext o FltDeleteContext.
Per determinare se i contesti di file sono supportati per un determinato file, chiamare FltSupportsFileContexts o FltSupportsFileContextsEx.
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 |