FltAttachVolumeAtAltitude 関数 (fltkernel.h)

[アーティクル]
03/08/2023

FltAttachVolumeAtAltitude は、ミニフィルタードライバーインスタンスを指定した高度のボリュームにアタッチし、ミニフィルタードライバーの INF ファイル内のすべての設定をオーバーライドするデバッグサポートルーチンです。

構文

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
);

パラメーター

[in, out] Filter

呼び出し元の不透明なフィルターポインター。このパラメーターは必須であり、 NULL にすることはできません。

[in, out] Volume

ミニフィルタードライバーインスタンスがアタッチされるボリュームの不透明なボリュームポインター。このパラメーターは必須であり、 NULL にすることはできません。

[in] Altitude

インスタンスの高度文字列を含む UNICODE_STRING 構造体へのポインター。このパラメーターは必須であり、 NULL にすることはできません。 (このパラメーターの詳細については、次の「解説」セクションを参照してください)。

[in, optional] InstanceName

新しいインスタンスのインスタンス名を含む UNICODE_STRING 構造体へのポインター。このパラメーターは省略可能であり、 NULL にすることができます。 NULL の場合、FltAttachVolumeAtAltitude はミニフィルタードライバー名と Altitude が指す高度文字列からインスタンス名を生成します。生成された名前は、必要に応じて文字をINSTANCE_NAME_MAX_CHARSするために切り捨てられます。

[out, optional] RetInstance

新しく作成されたインスタンスの不透明なインスタンスポインターを受け取る呼び出し元によって割り当てられた変数へのポインター。このパラメーターは省略可能であり、 NULL にすることができます。

戻り値

FltAttachVolumeAtAltitude は、次のいずれかのSTATUS_SUCCESSまたは適切な NTSTATUS 値を返します。

リターンコード	説明
STATUS_FLT_DELETING_OBJECT	指定したフィルターまたはボリュームが破棄されています。これはエラーコードです。
STATUS_FLT_FILTER_NOT_READY	ミニフィルタードライバーがフィルター処理を開始していません。詳細については、「 FltStartFiltering」を参照してください。これはエラーコードです。
STATUS_FLT_INSTANCE_ALTITUDE_COLLISION	インスタンスは、指定されたボリューム上のこの高度に既に存在します。これはエラーコードです。
STATUS_FLT_INSTANCE_NAME_COLLISION	指定されたボリュームに、この名前のインスタンスが既に存在します。これはエラーコードです。
STATUS_INSUFFICIENT_RESOURCES	FltAttachVolumeAtAltitude でプール割り当てエラーが発生しました。これはエラーコードです。
STATUS_INVALID_PARAMETER	Altitude が指すUNICODE_STRING構造に、有効な高度文字列が含まれていませんでした。これはエラーコードです。

注釈

ミニフィルタードライバーでは、デバッグに FltAttachVolumeAtAltitude のみを使用する必要があります。ミニフィルタードライバーの製品版では、このルーチンを呼び出さないでください。

FltAttachVolumeAtAltitude は、Win32 FilterAttachAtAltitude 関数に相当するカーネルです。

"altitude" という用語は、ボリュームのミニフィルタードライバーインスタンススタック内でインスタンスが占有する (または占有する必要がある) 位置を指します。高度が高いほど、インスタンスはスタック内の基本ファイルシステムから離れています。特定のボリュームの特定の高度にアタッチできるインスタンスは 1 つだけです。

高度は 高度文字列で指定されます。これは、0 から 9 までの 1 つ以上の 10 進数を含むワイド文字配列です。配列には 1 つの小数点を含めることができます。たとえば、"100.123456" と "03333" は有効な高度文字列です。

文字列 "03333" は、"100.123456" より高い高度を表します (先頭と末尾のゼロは無視されます)。つまり、高度が "03333" のインスタンスは、高度が "100.123456" のインスタンスよりもベースファイルシステムから離れています。ただし、この比較は、両方のインスタンスが同じボリュームにアタッチされている場合にのみ意味があります。

InstanceName パラメーターで指定されたインスタンス名は、システム全体で一意である必要があります。

FltAttachVolumeAtAltitude は 、*RetInstance 内の新しいインスタンスの不透明なインスタンスポインターを返します。このポインター値は、ミニフィルタードライバーインスタンスを一意に識別し、インスタンスがボリュームにアタッチされている限り一定のままになります。

FltAttachVolumeAtAltitude は 、*RetInstance で返される不透明なインスタンスポインターにランダウン参照を追加します。このポインターが不要になった場合、呼び出し元は FltObjectDereference を呼び出して解放する必要があります。したがって、 FltAttachVolumeAtAltitude の呼び出しが成功するたびに、 FltObjectDereference の後続の呼び出しと一致する必要があります。

同じボリュームにアタッチされている 2 つのミニフィルタードライバーインスタンスの高度を比較するには、 FltCompareInstanceAltitudes を呼び出します。

ミニフィルタードライバーインスタンスをボリュームからデタッチするには、 FltDetachVolume を呼び出します。