Funzione FltGetUpperInstance (fltkernel.h)

Articolo
02/06/2025

La routine FltGetUpperInstance restituisce un puntatore a un'istanza opaca per l'istanza successiva del driver minifilter superiore, se presente, collegata sopra una determinata istanza del driver minifilter nello stesso volume.

Sintassi

NTSTATUS FLTAPI FltGetUpperInstance(
  [in]  PFLT_INSTANCE CurrentInstance,
  [out] PFLT_INSTANCE *UpperInstance
);

Parametri

[in] CurrentInstance

Puntatore a un'istanza opaca per l'istanza per la quale viene richiesta l'istanza successiva.

[out] UpperInstance

Puntatore a una variabile allocata dal chiamante che riceve un puntatore a un'istanza opaca per l'istanza successiva superiore. Questo parametro è obbligatorio e non può essere NULL.

Valore restituito

FltGetUpperInstance restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio:

Codice restituito	Descrizione
STATUS_NO_MORE_ENTRIES	Non è stata trovata alcuna istanza superiore. Si tratta di un codice di avviso.

Osservazioni

Si dice che un'istanza sia sopra un'altra se è collegata a un'altitudine superiore sullo stesso volume. Il termine "altitudine" si riferisce alla posizione occupata da un'istanza (o deve occupare) nello stack di istanze del driver minifilter per un volume. Maggiore è l'altitudine, più lontana è l'istanza dal file system di base nello stack. Una sola istanza può essere collegata a una determinata altitudine su un determinato volume.

L'altitudine viene specificata da una stringa di altitudine , ovvero una stringa Unicode con conteggiata costituita da una o più cifre decimali nell'intervallo compreso tra 0 e 9 e può includere un singolo separatore decimale. Ad esempio, "100.123456" e "03333" sono stringhe di altitudine valide.

La stringa "03333" rappresenta un'altitudine superiore a "100.123456". Gli zeri 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 collegate allo stesso volume.

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