Funzione FltSetTransactionContext (fltkernel.h)

Articolo
02/29/2024

La routine FltSetTransactionContext imposta un contesto su una transazione.

Sintassi

NTSTATUS FLTAPI FltSetTransactionContext(
  [in]            PFLT_INSTANCE             Instance,
  [in]            PKTRANSACTION             Transaction,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Parametri

[in] Instance

Puntatore dell'istanza opaca per il chiamante.

[in] Transaction

Puntatore di transazione opaco per la transazione in cui viene impostato il contesto.

[in] Operation

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

Contrassegno	Significato
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Se un contesto è già impostato per la transazione a cui punta il parametro Transaction , FltSetTransactionContext lo sostituirà con il contesto a cui punta il parametro NewContext . In caso contrario, imposterà il contesto a cui punta il parametro NewContext come contesto per la transazione a cui punta il parametro Transaction .
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Se un contesto è già impostato per la transazione a cui punta il parametro Transaction , FltSetTransactionContext 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, questa routine imposterà il contesto a cui punta il parametro NewContext come contesto per la transazione a cui punta il parametro Transaction e incrementerà il conteggio dei riferimenti.

Contrassegno

Significato

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

Se un contesto è già impostato per la transazione a cui punta il parametro Transaction , FltSetTransactionContext lo sostituirà con il contesto a cui punta il parametro NewContext . In caso contrario, imposterà il contesto a cui punta il parametro NewContext come contesto per la transazione a cui punta il parametro Transaction .

FLT_SET_CONTEXT_KEEP_IF_EXISTS

Se un contesto è già impostato per la transazione a cui punta il parametro Transaction , FltSetTransactionContext 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, questa routine imposterà il contesto a cui punta il parametro NewContext come contesto per la transazione a cui punta il parametro Transaction e incrementerà il conteggio dei riferimenti.

[in] NewContext

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

[out, optional] OldContext

Puntatore a una variabile allocata dal chiamante che riceve l'indirizzo del contesto di transazione esistente, 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

FltSetTransactionContext 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 alla transazione. È possibile collegare un solo contesto a una transazione per un determinato driver minifilter.
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 Instance 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 transazione valido o è stato specificato un valore non valido per il parametro Operation . Si tratta di un codice di errore.

Commenti

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

Un driver minifilter chiama FltSetTransactionContext per collegare un contesto a una transazione o per rimuovere o sostituire un contesto di transazione esistente. Un driver minifilter può collegare un solo contesto a una determinata transazione.

Conteggio riferimenti

Se FltSetTransactionContext 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, fltSetTransactionContext 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 alla transazione. Il filtro che chiama FltSetTransactionContext deve chiamare FltReleaseContext per OldContext anche quando il puntatore di contesto non è più necessario.

Indipendentemente dal successo:

Il filtro che chiama FltSetTransactionContext 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 allocare un nuovo contesto, chiamare FltAllocateContext.

Per ottenere un contesto di transazione, chiamare FltGetTransactionContext.

Per eliminare un contesto di transazione, chiamare FltDeleteTransactionContext o FltDeleteContext.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile e supportato in Windows Vista e nei sistemi operativi successivi.
Piattaforma di destinazione	Universale
Intestazione	fltkernel.h (include Fltkernel.h)
Libreria	FltMgr.lib
DLL	FltMgr.sys
IRQL	<= APC_LEVEL.