Función FltGetVolumeGuidName (fltkernel.h)

Artículo
08/07/2023

FltGetVolumeGuidName obtiene el nombre del volumen de un volumen determinado, en formato de identificador único global (GUID) de volumen.

Sintaxis

NTSTATUS FLTAPI FltGetVolumeGuidName(
  [in]               PFLT_VOLUME     Volume,
  [in/out, optional] PUNICODE_STRING VolumeGuidName,
  [out, optional]    PULONG          BufferSizeNeeded
);

Parámetros

[in] Volume

Puntero opaco para el volumen. Debe ser un volumen del sistema de archivos local. Este parámetro es obligatorio y no puede ser NULL.

[in/out, optional] VolumeGuidName

Puntero a una estructura de UNICODE_STRING asignada por el autor de la llamada que recibe el nombre GUID del volumen cuando se devuelve STATUS_SUCCESS. Tenga en cuenta que el grupo de VolumeGuidName-Buffer> también está asignado por el autor de la llamada.

Si VolumeGuidName es NULL y BufferSizeNeeded no es NULL, FltGetVolumeGuidName almacena el tamaño de búfer necesario para el GUID de volumen solicitado en el parámetro BufferSizeNeeded y devuelve STATUS_BUFFER_TOO_SMALL. Vea la sección Comentarios.

[out, optional] BufferSizeNeeded

Puntero a una variable asignada por el autor de la llamada que recibe el tamaño, en bytes, del nombre GUID del volumen solicitado. Este parámetro es opcional y puede ser NULL; Sin embargo, debe ser distinto de NULL si VolumeGuidName es NULL para que FltGetVolumeGuidName pueda almacenar el tamaño del búfer necesario para el GUID del volumen solicitado.

Valor devuelto

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

Código devuelto	Descripción
STATUS_BUFFER_TOO_SMALL	El búfer al que apunta VolumeGuidName es NULL o demasiado pequeño para contener el GUID del volumen. Si el llamador proporciona un valor distinto de NULL para BufferSizeNeeded, FltGetVolumeGuidName almacena el tamaño de búfer necesario en BufferSizeNeeded. Esto se considera un código de error porque no se recuperó el nombre del GUID del volumen.
STATUS_INSUFFICIENT_RESOURCES	FltGetVolumeGuidName encontró un error de asignación de grupo. Se trata de un código de error.
STATUS_INVALID_DEVICE_REQUEST	El parámetro Volume es un identificador para un volumen de red. Se trata de un código de error.
STATUS_FLT_VOLUME_NOT_FOUND	No se encontró ningún volumen coincidente. Se trata de un código de error.

Comentarios

El nombre GUID del volumen devuelto se expresa en el siguiente formato:

\?? \Volume{GUID}

donde GUID es un identificador único global que identifica el volumen. Este formato, que es el mismo que el usado por el administrador de montaje, se describe en Admitir solicitudes del Administrador de montaje en un controlador de clase de almacenamiento.

Si BufferSizeNeeded es desconocido, llame a FltGetVolumeGuidName dos veces:

En la primera llamada, establezca VolumeGuidName en NULL y BufferSizeNeeded en distinto de NULL. FltGetVolumeGuidName almacenará el número de bytes necesarios para el GUID del nombre de volumen en BufferSizeNeeded y devolverá STATUS_BUFFER_TOO_SMALL.
En la segunda llamada, establezca VolumeGuidName para que apunte a una estructura que sea el tamaño del valor BufferSizeNeeded devuelto en la primera llamada.

FltGetVolumeGuidName no se puede llamar de forma segura desde una devolución de llamada anterior o posterior al montaje. No se puede llamar de forma segura porque incluso cuando se llama a la devolución de llamada posterior al montaje, el administrador de E/S no ha completado el procesamiento de montaje y esto provoca un interbloqueo con el administrador de montaje en determinados casos.

En Windows Vista y versiones posteriores, un controlador de minifiltro puede llamar de forma segura a FltGetVolumeGuidName desde su rutina InstanceSetupCallback (PFLT_INSTANCE_SETUP_CALLBACK) porque se llama a la devolución de llamada en la primera operación de E/S para un nuevo volumen una vez completado todo el procesamiento del montaje.

En los sistemas operativos Windows anteriores a Windows Vista, fltGetVolumeGuidName no se puede llamar de forma segura desde una rutina InstanceSetupCallback porque el administrador de montaje podría emitir una operación de E/S de archivos mientras mantiene un bloqueo, lo que puede provocar un interbloqueo.

Es importante tener en cuenta que el GUID del volumen no es el mismo que el identificador del objeto de volumen. El GUID del volumen, o nombre de volumen único, es un valor independiente del sistema de archivos; el administrador de montaje asigna al volumen de almacenamiento subyacente. El sistema de archivos asigna el identificador de objeto de volumen al volumen del sistema de archivos.

Para obtener el identificador de objeto de volumen de un volumen, llame a ZwQueryVolumeInformationFile y especifique FileFsObjectIdInformation para el parámetro FsInformationClass .

FltGetVolumeGuidName es aproximadamente equivalente a la función GetVolumeNameForVolumeMountPoint de Win32. (GetVolumeNameForVolumeMountPoint se documenta en el Microsoft Windows SDK).