Condividi tramite

Funzione FltSetInstanceContext (fltkernel.h)

  • Articolo

FltSetInstanceContext imposta un contesto per un'istanza del driver minifiltro.

Sintassi

NTSTATUS FLTAPI FltSetInstanceContext(
  [in]  PFLT_INSTANCE             Instance,
  [in]  FLT_SET_CONTEXT_OPERATION Operation,
  [in]  PFLT_CONTEXT              NewContext,
  [out] PFLT_CONTEXT              *OldContext
);

Parametri

[in] Instance

Puntatore dell'istanza opaca per l'istanza.

[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 l'istanza a cui punta il parametro Istanza di, FltSetInstanceContext sostituirà tale contesto con il contesto specificato in NewContext. In caso contrario, verrà impostato NewContext come contesto per Istanza.
FLT_SET_CONTEXT_KEEP_IF_EXISTS Se per questa istanza di è già impostato un contesto, FltSetInstanceContext restituisce STATUS_FLT_CONTEXT_ALREADY_DEFINED e non sostituisce il contesto esistente o incrementa il conteggio dei riferimenti. Se un contesto non è già impostato, la routine imposta NewContext come contesto per Istanza e incrementa il conteggio dei riferimenti.

[in] NewContext

Puntatore al nuovo contesto da impostare per l'istanza. Questo parametro è obbligatorio e non può essere NULL.

[out] OldContext

Puntatore a una variabile allocata dal chiamante che riceve l'indirizzo del contesto dell'istanza esistente, se ne è già impostata una. Questo parametro è facoltativo e può essere NULL. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguente.

Valore restituito

fltSetInstanceContext 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 all'istanza di . È possibile collegare un solo contesto a un'istanza di .
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 file valido oppure è stato specificato un valore non valido per il parametro operation. Si tratta di un codice di errore.

Osservazioni

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

Un driver minifilter chiama FltSetInstanceContext per collegare un contesto di istanza a un'istanza del driver minifilter di proprietà del chiamante oppure per rimuovere o sostituire un contesto di istanza esistente. Un driver minifiltro può collegare un solo contesto a un'istanza di .

Conteggio dei riferimenti

Se FltSetInstanceContext ha esito positivo:

  • Il conteggio dei riferimenti per NewContext viene incrementato. Quando il contesto a cui punta NewContext non è più necessario, il minifiltro deve chiamare FltReleaseContext per decrementare il numero di riferimenti.

Altrimenti se FltSetInstanceContext 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 all'istanza di . Il filtro che chiama FltSetInstanceContext deve infine chiamare fltReleaseContext per OldContext e quando il puntatore di contesto non è più necessario.

Indipendentemente dall'esito positivo:

  • Il filtro che chiama FltSetInstanceContext deve chiamare FltReleaseContext per decrementare il conteggio dei riferimenti sull'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 versioni successive del sistema operativo.
piattaforma di destinazione Universale
intestazione fltkernel.h (include Fltkernel.h)
libreria FltMgr.lib
dll Fltmgr.sys
IRQL <= APC_LEVEL

Vedere anche

FltAllocateContext

FltDeleteContext

FltDeleteInstanceContext

FltGetInstanceContext

FltReleaseContext