Función FltGetVolumeInstanceFromName (fltkernel.h)

La rutina FltGetVolumeInstanceFromName devuelve un puntero de instancia opaco para la instancia de controlador de minifiltro especificada en el volumen especificado.

Sintaxis

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

Parámetros

[in, optional] Filter

Puntero de filtro opaco para el controlador de minifiltro que posee la instancia. Este parámetro es opcional y se puede NULL.

[in] Volume

Puntero opaco para el volumen al que está asociada la instancia. Debe ser un identificador de volumen válido. Este parámetro es necesario y no se puede null. (Establecer este parámetro en un valor no válido hace que el sistema aserte en una compilación comprobada).

[in, optional] InstanceName

Puntero a una estructura de UNICODE_STRING asignada por el autor de la llamada que contiene el nombre de instancia de la instancia del volumen. (Este es el valor instanceName que se pasó a FltAttachVolume o FltAttachVolumeAtAltitude cuando se creó la instancia). Este parámetro es opcional y se puede NULL. Si es null, FltGetVolumeInstanceFromName devuelve la instancia coincidente más alta que se encuentra.

[out] RetInstance

Puntero a una variable asignada por el autor de la llamada que recibe un puntero de instancia opaco para la instancia que coincide con los valores de Filter, Volumey InstanceName. Este parámetro es necesario y no se puede null.

Valor devuelto

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

Código devuelto Descripción
STATUS_FLT_DELETING_OBJECT
La instancia se está descomponiéndose. Se trata de un código de error.
STATUS_FLT_INSTANCE_NOT_FOUND
No se encontró ninguna instancia coincidente. Se trata de un código de error.

Observaciones

FltGetVolumeInstanceFromName busca en la lista de instancias del controlador de minifiltro asociadas al volumen especificado en el parámetro Volume para reducir la altitud, empezando por la instancia superior. Si más de una instancia coincide con los valores especificados para los parámetros Filter, Volumey parámetros instanceName, FltGetVolumeInstanceFromName devuelve la instancia coincidente más alta que se encuentra.

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 cadena Unicode con recuento que consta de uno o varios dígitos decimales de 0 a 9, y 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.

FltGetVolumeInstanceFromName agrega una referencia de rundown al puntero de instancia opaco devuelto en el parámetro 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 FltGetVolumeInstanceFromName debe coincidir con una llamada posterior a FltObjectDereference.

Requisitos

Requisito Valor
de la plataforma de destino de Universal
encabezado de fltkernel.h (incluya Fltkernel.h)
biblioteca de FltMgr.lib
DLL de Fltmgr.sys
irQL <= APC_LEVEL

Consulte también

fltAttachVolume

FltAttachVolumeAtAltitude

FltObjectDereference

UNICODE_STRING