Condividi tramite

Funzione FltSetStreamContext (fltkernel.h)

  • Articolo

La routine FltSetStreamContext imposta un contesto per un flusso di file.

Sintassi

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

Parametri

[in] Instance

Puntatore a un'istanza opaca per l'istanza del driver minifilter il cui contesto deve essere inserito, rimosso o sostituito nell'elenco di contesti collegati al flusso di file.

[in] FileObject

Puntatore a un oggetto file per il flusso di file.

[in] Operation

Flag che specifica i dettagli dell'operazione da eseguire. Questo parametro deve essere uno dei seguenti:

Bandiera Significato
FLT_SET_CONTEXT_REPLACE_IF_EXISTS Se un contesto è già impostato per Instance, FltSetStreamContext lo sostituirà con il contesto specificato in NewContext. In caso contrario, inserirà NewContext nell'elenco dei contesti per il flusso di file.
FLT_SET_CONTEXT_KEEP_IF_EXISTS Se per questa istanza di è già impostato un contesto, FltSetStreamContext 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 NewContext nell'elenco di contesti per il flusso di file e incrementa il conteggio dei riferimenti.

[in] NewContext

Puntatore al nuovo contesto da impostare per il flusso di 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 flusso esistente per il parametro Istanza di, 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 FltSetStreamContext 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 Operation, questo codice di errore indica che un contesto di flusso è già collegato al flusso di file.
STATUS_FLT_CONTEXT_ALREADY_LINKED Il contesto a cui punta 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 Istanza di 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 flusso valido oppure è stato specificato un valore non valido per il parametro Operation. Si tratta di un codice di errore.
STATUS_NOT_SUPPORTED Il file system non supporta i contesti per flusso per questo flusso di file. Si tratta di un codice di errore.

Osservazioni

Per altre informazioni sui contesti, vedere Informazioni sui contesti del minifiltro.

Un driver minifilter chiama FltSetStreamContext per collegare un contesto di flusso a un flusso di file oppure per rimuovere o sostituire un contesto di flusso esistente. Un driver minifilter può collegare un contesto per ogni istanza del driver minifilter al flusso di file.

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

Conteggio dei riferimenti

Se FltSetStreamContext ha esito positivo:

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

Altrimenti se FltSetStreamContext ha esito negativo:

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

Indipendentemente dall'esito positivo:

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

Per altre informazioni, vedere Riferimento ai contesti.

Altre operazioni di contesto

Per altre informazioni, vedere Setting Contextse Releasing Contexts:

Fabbisogno

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

Vedere anche

FltAllocateContext

FltDeleteContext

FltDeleteStreamContext

FltGetStreamContext

FltReleaseContext