Funzione FltSetVolumeContext (fltkernel.h)

Articolo
08/07/2023

FltSetVolumeContext imposta un contesto per un volume.

Sintassi

NTSTATUS FLTAPI FltSetVolumeContext(
  [in]            PFLT_VOLUME               Volume,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Parametri

[in] Volume

Puntatore al volume opaco per il volume.

[in] Operation

Contrassegno 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 Volume, FltSetVolumeContext lo sostituirà con NewContext>. In caso contrario, verrà inserito NewContext nell'elenco di contesti per il volume.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Se un contesto è già impostato per questo volume, FltSetVolumeContext 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 volume e incrementa il conteggio dei riferimenti.

[in] NewContext

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

[out, optional] OldContext

Puntatore a una variabile allocata dal chiamante che riceve l'indirizzo del contesto del volume esistente per Volume. Questo parametro è facoltativo e può essere NULL. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguenti.

Valore restituito

FltSetVolumeContext 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 è già collegato al volume.
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	Il volume specificato viene eliminato. 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 volume valido o un valore non valido è stato specificato per Operation. Si tratta di un codice di errore.

Commenti

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

Un driver minifilter chiama FltSetVolumeContext per collegare un contesto a un volume o per rimuovere o sostituire un contesto di volume esistente. Un driver minifilter può collegare un solo contesto a un volume.

Conteggio dei riferimenti

Se FltSetVolumeContext 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 FltSetVolumeContext 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 volume. Il filtro che chiama FltSetVolumeContext deve chiamare FltReleaseContext per OldContext e quando il puntatore del contesto non è più necessario.

Indipendentemente dal successo:

Il filtro che chiama FltSetVolumeContext deve chiamare FltReleaseContext per decrerere 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 del volume, chiamare FltGetVolumeContext.
Per eliminare un contesto del volume, chiamare FltDeleteVolumeContext 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 (includere Fltkernel.h)
Libreria	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL