Función FltAttachVolumeAtAltitude (fltkernel.h)

Artículo
02/06/2025

FltAttachVolumeAtAltitude es una rutina de compatibilidad de depuración que asocia una instancia de controlador de minifiltro a un volumen a una altitud especificada, reemplazando cualquier configuración en el archivo INF del controlador de minifiltro.

Sintaxis

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

Parámetros

[in, out] Filter

Puntero de filtro opaco para el autor de la llamada. Este parámetro es necesario y no se puede null.

[in, out] Volume

Puntero de volumen opaco para el volumen al que se va a adjuntar la instancia del controlador de minifiltro. Este parámetro es necesario y no se puede null.

[in] Altitude

Puntero a una estructura UNICODE_STRING que contiene la cadena de altitud de la instancia. Este parámetro es necesario y no se puede null. (Para obtener más información sobre este parámetro, vea la siguiente sección Comentarios).

[in, optional] InstanceName

Puntero a una estructura de UNICODE_STRING que contiene el nombre de instancia de la nueva instancia. Este parámetro es opcional y se puede NULL. Si es NULL, FltAttachVolumeAtAltitude genera un nombre de instancia del nombre del controlador de minifiltro y la cadena de altitud a la que Altitud apunta. El nombre generado se trunca, si es necesario, para INSTANCE_NAME_MAX_CHARS caracteres.

[out, optional] RetInstance

Puntero a una variable asignada por el autor de la llamada que recibe un puntero de instancia opaco para la instancia recién creada. Este parámetro es opcional y se puede NULL.

Valor devuelto

fltAttachVolumeAtAltitude devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes:

Código devuelto	Descripción
STATUS_FLT_DELETING_OBJECT	El de filtro de especificado o volumen se está descomponiéndose. Se trata de un código de error.
STATUS_FLT_FILTER_NOT_READY	El controlador de minifiltro no ha iniciado el filtrado. Para obtener más información, vea FltStartFiltering. Se trata de un código de error.
STATUS_FLT_INSTANCE_ALTITUDE_COLLISION	Ya existe una instancia en esta altitud en el volumen especificado. Se trata de un código de error.
STATUS_FLT_INSTANCE_NAME_COLLISION	Ya existe una instancia con este nombre en el volumen especificado. Se trata de un código de error.
STATUS_INSUFFICIENT_RESOURCES	fltAttachVolumeAtAltitude encontró un error de asignación de grupo. Se trata de un código de error.
STATUS_INVALID_PARAMETER	La estructura UNICODE_STRING que altitud apunta a que no contenía una cadena de altitud válida. Se trata de un código de error.

Observaciones

Un controlador de minifiltro solo debe usar fltAttachVolumeAtAltitude para la depuración. No debe llamar a esta rutina en una versión comercial del controlador de minifiltro.

fltAttachVolumeAtAltitude es el equivalente del kernel de la función FilterAttachAtAltitude de Win3 2.

El término "altitud" hace referencia a la posición que ocupa una instancia (o debe ocupar) en la pila de instancias del controlador de minifiltro para un volumen. Cuanto mayor sea la altitud, más lejos estará la instancia del sistema de archivos base de la pila. Solo se puede adjuntar una instancia a una altitud determinada en un volumen determinado.

La altitud se especifica mediante una cadena de altitud, que es una matriz de caracteres anchos que contiene uno o varios dígitos decimales de 0 a 9; la matriz puede incluir un único separador decimal. Por ejemplo, "100.123456" y "03333" son cadenas de altitud válidas.

La cadena "03333" representa una altitud mayor que "100.123456" (se omiten los ceros iniciales y finales). Es decir, una instancia cuya altitud es "03333" está más lejos del sistema de archivos base que una instancia cuya altitud es "100.123456". Sin embargo, esta comparación solo es significativa si ambas instancias están asociadas al mismo volumen.

El nombre de instancia especificado en el parámetro InstanceName debe ser único en todo el sistema.

fltAttachVolumeAtAltitude devuelve un puntero de instancia opaco para la nueva instancia en *RetInstance. Este valor de puntero identifica de forma única la instancia del controlador de minifiltro y permanece constante siempre que la instancia esté asociada al volumen.

FltAttachVolumeAtAltitude agrega una referencia de rundown al puntero de instancia opaco devuelto en *RetInstance. Cuando este puntero ya no es necesario, el autor de la llamada debe liberarlo llamando a FltObjectDereference. Por lo tanto, cada llamada correcta a FltAttachVolumeAtAltitude debe coincidir con una llamada posterior a FltObjectDereference.

Para comparar las altitudes de dos instancias de controlador de minifiltro asociadas al mismo volumen, llame a FltCompareInstanceAltitudes.

Para desasociar una instancia de controlador de minifiltro de un volumen, llame a FltDetachVolume.