Funzione FltGetVolumeInstanceFromName (fltkernel.h)

La routine FltGetVolumeInstanceFromName restituisce un puntatore di istanza opaco per l'istanza del driver minifilter specificata nel volume specificato.

Sintassi

NTSTATUS FLTAPI FltGetVolumeInstanceFromName(
  [in, optional] PFLT_FILTER      Filter,
  [in]           PFLT_VOLUME      Volume,
  [in, optional] PCUNICODE_STRING InstanceName,
  [out]          PFLT_INSTANCE    *RetInstance
);

Parametri

[in, optional] Filter

Puntatore di filtro opaco per il driver minifilter proprietario dell'istanza. Questo parametro è facoltativo e può essere NULL.

[in] Volume

Puntatore opaco per il volume a cui è associata l'istanza. Deve essere un handle del volume valido. Questo parametro è obbligatorio e non può essere NULL. L'impostazione di questo parametro su un valore non valido causa l'asserzione del sistema in una build selezionata.

[in, optional] InstanceName

Puntatore a una struttura UNICODE_STRING allocata dal chiamante che contiene il nome dell'istanza per l'istanza nel volume. Questo è il valore InstanceName passato a FltAttachVolume o FltAttachVolumeAtAltitude quando l'istanza è stata creata. Questo parametro è facoltativo e può essere NULL. Se è NULL, FltGetVolumeInstanceFromName restituisce l'istanza corrispondente più elevata trovata.

[out] RetInstance

Puntatore a una variabile allocata dal chiamante che riceve un puntatore di istanza opaca per l'istanza corrispondente ai valori per Filter, Volume e InstanceName. Questo parametro è obbligatorio e non può essere NULL.

Valore restituito

FltGetVolumeInstanceFromName restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_FLT_DELETING_OBJECT	L'istanza viene distrutta. Si tratta di un codice di errore.
STATUS_FLT_INSTANCE_NOT_FOUND	Non è stata trovata alcuna istanza corrispondente. Si tratta di un codice di errore.

Commenti

FltGetVolumeInstanceFromName cerca l'elenco delle istanze del driver minifilter associate al volume specificato nel parametro Volume in ordine di diminuzione dell'altitudine, a partire dall'istanza superiore. Se più di un'istanza corrisponde ai valori specificati per i parametri Filter, Volume e InstanceName , FltGetVolumeInstanceFromName restituisce l'istanza corrispondente più elevata trovata.

Il termine "altitudine" fa riferimento alla posizione che un'istanza occupa (o deve occupare) nello stack di istanze del driver minifilter per un volume. Maggiore è l'altitudine, più lontano l'istanza è dal file system di base nello stack. È possibile collegare un'unica istanza a una determinata altitudine in un determinato volume.

L'altitudine è specificata da una stringa di altitudine, ovvero una stringa Unicode conteggiata costituita da una o più cifre decimali da 0 a 9 e può includere un singolo punto decimale. Ad esempio, "100.123456" e "03333" sono stringhe di altitudine valide.

La stringa "03333" rappresenta un'altitudine superiore a "100.123456". I valori iniziali e finali vengono ignorati. In altre parole, un'istanza la cui altitudine è "03333" è più lontana dal file system di base rispetto a un'istanza la cui altitudine è "100.123456". Tuttavia, questo confronto è significativo solo se entrambe le istanze sono associate allo stesso volume.

FltGetVolumeInstanceFromName aggiunge un riferimento di rundown al puntatore dell'istanza opaca restituito nel parametro RetInstance . Quando questo puntatore non è più necessario, il chiamante deve rilasciarlo chiamando FltObjectDereference. Pertanto ogni chiamata riuscita a FltGetVolumeInstanceFromName deve essere corrispondente a una chiamata successiva a FltObjectDereference.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	fltkernel.h (includere Fltkernel.h)
Libreria	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL

Vedi anche

FltAttachVolume

FltAttachVolumeAtAltitude

FltObjectDereference

UNICODE_STRING