Funzione FltAttachVolumeAtAltitude (fltkernel.h)

Articolo
03/08/2023

FltAttachVolumeAtAltitude è una routine di supporto per il debug che collega un'istanza del driver minifilter a un volume a un'altitudine specificata, eseguendo l'override di tutte le impostazioni nel file INF del driver minifilter.

Sintassi

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

Parametri

[in, out] Filter

Puntatore di filtro opaco per il chiamante. Questo parametro è obbligatorio e non può essere NULL.

[in, out] Volume

Puntatore al volume opaco per il volume a cui deve essere collegata l'istanza del driver minifilter. Questo parametro è obbligatorio e non può essere NULL.

[in] Altitude

Puntatore a una struttura UNICODE_STRING contenente la stringa di altitudine per l'istanza. Questo parametro è obbligatorio e non può essere NULL. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguente.

[in, optional] InstanceName

Puntatore a una struttura UNICODE_STRING contenente il nome dell'istanza per la nuova istanza. Questo parametro è facoltativo e può essere NULL. Se è NULL, FltAttachVolumeAtAltitude genera un nome di istanza dal nome del driver minifilter e dalla stringa di altitudine a cui Punta Altitude . Il nome generato viene troncato, se necessario, per INSTANCE_NAME_MAX_CHARS caratteri.

[out, optional] RetInstance

Puntatore a una variabile allocata dal chiamante che riceve un puntatore di istanza opaco per l'istanza appena creata. Questo parametro è facoltativo e può essere NULL.

Valore restituito

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

Codice restituito	Descrizione
STATUS_FLT_DELETING_OBJECT	Il filtro o il volume specificato viene eliminato. Si tratta di un codice di errore.
STATUS_FLT_FILTER_NOT_READY	Il driver minifilter non ha avviato il filtro. Per altre informazioni, vedere FltStartFiltering. Si tratta di un codice di errore.
STATUS_FLT_INSTANCE_ALTITUDE_COLLISION	Un'istanza esiste già a questa altitudine nel volume specificato. Si tratta di un codice di errore.
STATUS_FLT_INSTANCE_NAME_COLLISION	Esiste già un'istanza con questo nome nel volume specificato. Si tratta di un codice di errore.
STATUS_INSUFFICIENT_RESOURCES	FltAttachVolumeAtAltitude ha rilevato un errore di allocazione del pool. Si tratta di un codice di errore.
STATUS_INVALID_PARAMETER	La struttura UNICODE_STRING a cui punta Altitude non contiene una stringa di altitudine valida. Si tratta di un codice di errore.

Commenti

Un driver minifilter deve usare solo FltAttachVolumeAtAltitude per il debug. Non deve chiamare questa routine in una versione definitiva del driver minifilter.

FltAttachVolumeAtAltitude è l'equivalente kernel della funzione FilterAttachAtAltitude Win32.

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. È possibile collegare una sola istanza a una determinata altitudine in un determinato volume.

L'altitudine viene specificata da una stringa di altitudine, che è una matrice di caratteri wide contenente una o più cifre decimali da 0 a 9; la matrice 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.

Il nome dell'istanza specificato nel parametro InstanceName deve essere univoco nel sistema.

FltAttachVolumeAtAltitude restituisce un puntatore di istanza opaco per la nuova istanza in *RetInstance. Questo valore del puntatore identifica in modo univoco l'istanza del driver minifilter e rimane costante finché l'istanza è collegata al volume.

FltAttachVolumeAtAltitude aggiunge un riferimento rundown al puntatore di istanza opaco restituito in *RetInstance. Quando questo puntatore non è più necessario, il chiamante deve rilasciarlo chiamando FltObjectDereference. Ogni chiamata riuscita a FltAttachVolumeAtAltitude deve quindi corrispondere a una chiamata successiva a FltObjectDereference.

Per confrontare le altitudini di due istanze del driver minifilter collegate allo stesso volume, chiamare FltCompareInstanceAltitudes.

Per scollegare un'istanza del driver minifilter da un volume, chiamare FltDetachVolume.