Funzione FltSetStreamHandleContext (fltkernel.h)
La routine FltSetStreamHandleContext imposta un contesto per un handle di flusso.
Sintassi
NTSTATUS FLTAPI FltSetStreamHandleContext(
[in] PFLT_INSTANCE Instance,
[in] PFILE_OBJECT FileObject,
[in] FLT_SET_CONTEXT_OPERATION Operation,
[in] PFLT_CONTEXT NewContext,
[out, optional] PFLT_CONTEXT *OldContext
);
Parametri
[in] Instance
Puntatore di istanza opaco per l'istanza del driver minifilter il cui contesto deve essere inserito, rimosso o sostituito nell'elenco di contesti collegati all'handle di flusso.
[in] FileObject
Puntatore a un oggetto file per il flusso di file. Questo parametro è obbligatorio e non può essere NULL.
[in] Operation
Flag che specifica i dettagli dell'operazione da eseguire. Questo parametro deve essere uno dei seguenti:
| Valore | Significato |
|---|---|
| FLT_SET_CONTEXT_REPLACE_IF_EXISTS | Se un contesto è già impostato per questa istanza, FltSetStreamHandleContext lo sostituirà con il contesto specificato in NewContext. In caso contrario, verrà inserito NewContext nell'elenco di contesti per l'handle del flusso. |
| FLT_SET_CONTEXT_KEEP_IF_EXISTS | Se un contesto è già impostato per questa istanza, FltSetStreamHandleContext restituirà STATUS_FLT_CONTEXT_ALREADY_DEFINED e non sostituirà il contesto esistente o incrementerà il conteggio dei riferimenti. Se non è già stato impostato un contesto, la routine inserisce NewContext nell'elenco di contesti per l'handle del flusso e incrementa il conteggio dei riferimenti. |
[in] NewContext
Puntatore al nuovo contesto da impostare per l'handle di flusso. Questo parametro è obbligatorio e non può essere NULL.
[out, optional] OldContext
Puntatore a una variabile allocata dal chiamante che riceve l'indirizzo del contesto dell'handle di flusso esistente per 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 seguente.
Valore restituito
La routine FltSetStreamHandleContext restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei codici di errore seguenti:
| Codice restituito | Descrizione |
|---|---|
| STATUS_FLT_CONTEXT_ALREADY_DEFINED | Se FLT_SET_CONTEXT_KEEP_IF_EXISTS è stato specificato per Operation, questo codice di errore indica che un contesto è già collegato all'handle del flusso. |
| STATUS_FLT_CONTEXT_ALREADY_LINKED | Il contesto a cui punta 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 viene distrutta. 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 handle di flusso valido oppure per Operation è stato specificato un valore non valido. |
| STATUS_NOT_SUPPORTED | Si è verificata una situazione non supportata, ad esempio il file system non supporta i contesti per flusso per questo flusso di file o il chiamante ha fornito un FileObject NULL. |
Commenti
Per altre informazioni sui contesti, vedere Informazioni sui contesti minifilter.
La routine FltSetStreamHandleContext aggiunge, rimuove o sostituisce un contesto per un'istanza del driver minifilter in un handle di flusso. Un driver minifilter può collegare un contesto per ogni istanza del driver minifilter all'handle di flusso.
Non è possibile chiamare FltSetStreamHandleContext in un FileObject non aperto. Di conseguenza , FltSetStreamHandleContext non può essere chiamato da un callback di pre-creazione per un flusso perché il flusso non è stato aperto a quel punto. Un minifilter può, tuttavia, allocare e configurare il contesto dell'handle di flusso nel callback di pre-creazione, passarlo al callback post-create usando il parametro di contesto di completamento e impostare il contesto dell'handle di flusso nel flusso nel callback post-creazione.
Conteggio riferimenti
Se FltSetStreamHandleContext ha esito positivo:
- Il conteggio dei riferimenti in NewContext viene incrementato. Quando NewContext non è più necessario, il minifilter deve chiamare FltReleaseContext per decrementare il conteggio dei riferimenti.
In caso contrario, fltSetStreamHandleContext ha esito negativo:
- Il conteggio dei riferimenti in NewContext rimane invariato.
- Se OldContext non è NULL e non punta a NULL_CONTEXT , OldContext è un puntatore a cui si fa riferimento al contesto attualmente associato all'handle di flusso. Il filtro che chiama FltSetStreamHandleContext deve chiamare FltReleaseContext per OldContext , anche quando il puntatore di contesto non è più necessario.
Indipendentemente dal successo:
- Il filtro che chiama FltSetStreamHandleContext deve chiamare FltReleaseContext per decrementare il conteggio dei riferimenti sull'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 determinare se i contesti di handle del flusso sono supportati per un determinato file, chiamare FltSupportsStreamHandleContexts
Per allocare un nuovo contesto, chiamare FltAllocateContext.
Per ottenere un contesto di handle di flusso, chiamare FltGetStreamHandleContext.
Per eliminare un contesto di handle di flusso, chiamare FltDeleteStreamHandleContext o FltDeleteContext.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile e supportato in Microsoft Windows 2000 Update Rollup 1 per SP4, Windows XP SP2, Windows Server 2003 SP1 e sistemi operativi successivi. |
| Piattaforma di destinazione | Universale |
| Intestazione | fltkernel.h (include Fltkernel.h) |
| Libreria | Fltmgr.lib |
| DLL | Fltmgr.sys |
| IRQL | <= APC_LEVEL |