Función FltGetVolumeGuidName (fltkernel.h)

Artículo
12/21/2024

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 necesario y no se puede 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 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 serNULL si volumeGuidName es NULL para que FltGetVolumeGuidName pueda almacenar el tamaño de 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 autor de la llamada proporciona un valor null que no esNULL 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.

Observaciones

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 solicitudes auxiliares del Administrador de montaje en un controlador de clase de almacenamiento.

Si se desconoce bufferSizeNeededed, llame a FltGetVolumeGuidName dos veces:

En la primera llamada, establezca VolumeGuidName en NULL y BufferSizeNeeded enNULL. fltGetVolumeGuidName almacenará el número de bytes necesarios para el GUID de 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 de 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 del 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 a FltGetVolumeGuidName desde su InstanceSetupCallback rutina (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 después de que se complete 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 presionado 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 de objeto de volumen. El GUID de 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 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, especificando fileFsObjectIdInformation para el parámetro FsInformationClass de .

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