Função FltGetVolumeGuidName (fltkernel.h)

Artigo
12/21/2024

FltGetVolumeGuidName obtém o nome do volume de um determinado volume, no formato GUID (identificador global exclusivo) do volume.

Sintaxe

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

Parâmetros

[in] Volume

Ponteiro opaco para o volume. Deve ser um volume do sistema de arquivos local. Esse parâmetro é necessário e não pode ser NULL.

[in/out, optional] VolumeGuidName

Ponteiro para uma estrutura de UNICODE_STRING alocada pelo chamador que recebe o nome GUID do volume quando STATUS_SUCCESS é retornado. Lembre-se de que o pool para VolumeGuidName->Buffer também é alocado por chamador.

Se VolumeGuidName for NULL e BufferSizeNeeded não NULL, FltGetVolumeGuidName armazenará o tamanho do buffer necessário para o GUID de volume solicitado no parâmetro BufferSizeNeeded do e retornará STATUS_BUFFER_TOO_SMALL. Consulte Comentários.

[out, optional] BufferSizeNeeded

Ponteiro para uma variável alocada por chamador que recebe o tamanho, em bytes, do nome guid do volume solicitado. Esse parâmetro é opcional e pode ser NULL; no entanto, ele deve ser NULL nãose VolumeGuidName estiver NULL para que FltGetVolumeGuidName possa armazenar o tamanho do buffer necessário para o GUID de volume solicitado.

Valor de retorno

fltGetVolumeGuidName retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_BUFFER_TOO_SMALL	O buffer apontado por VolumeGuidName é NULL ou muito pequeno para manter o GUID de volume. Se o chamador fornecer um valor NULL nãopara BufferSizeNeeded, FltGetVolumeGuidName armazenará o tamanho do buffer necessário em BufferSizeNeeded. Isso é considerado um código de erro, pois o nome GUID do volume não foi recuperado.
STATUS_INSUFFICIENT_RESOURCES	FltGetVolumeGuidName encontrou uma falha de alocação de pool. Este é um código de erro.
STATUS_INVALID_DEVICE_REQUEST	O parâmetro Volume é um identificador para um volume de rede. Este é um código de erro.
STATUS_FLT_VOLUME_NOT_FOUND	Nenhum volume correspondente foi encontrado. Este é um código de erro.

Observações

O nome GUID do volume retornado é expresso no seguinte formato:

\?? \Volume{GUID}

em que GUID é um identificador global exclusivo que identifica o volume. Esse formato, que é o mesmo usado pelo gerenciador de montagem, é descrito em suporte a solicitações do Mount Manager em um driver de classe de armazenamento.

Se BufferSizeNeeded for desconhecido, chame FltGetVolumeGuidName duas vezes:

Na primeira chamada, defina VolumeGuidName como NULL e BufferSizeNeeded paraNULL não. FltGetVolumeGuidName armazenará o número de bytes necessários para o GUID de nome de volume em BufferSizeNeeded e retornará STATUS_BUFFER_TOO_SMALL.
Na segunda chamada, defina VolumeGuidName para apontar para uma estrutura que seja do tamanho do valor BufferSizeNeeded retornado na primeira chamada.

FltGetVolumeGuidName não pode ser chamado com segurança de um retorno de chamada pré-montagem ou pós-montagem. Ele não pode ser chamado com segurança porque, mesmo quando o retorno de chamada pós-montagem é chamado, o processamento de montagem não foi concluído pelo gerente de E/S e isso causa um deadlock com o gerenciador de montagem em determinados casos.

No Windows Vista e posterior, um driver de minifiltro pode chamar com segurança FltGetVolumeGuidName de sua rotina de InstanceSetupCallback (PFLT_INSTANCE_SETUP_CALLBACK) porque o retorno de chamada é chamado na primeira operação de E/S para um novo volume depois que todo o processamento de montagem é concluído.

Em sistemas operacionais Windows anteriores ao Windows Vista, FltGetVolumeGuidName não pode ser chamado com segurança de uma rotina de InstanceSetupCallback porque o gerenciador de montagem pode emitir uma operação de E/S de arquivo enquanto mantém um bloqueio, o que pode causar um deadlock.

É importante observar que o GUID de volume não é o mesmo que a ID do objeto de volume. O GUID de volumeou nome de volume exclusivo, é um valor independente do sistema de arquivos; ele é atribuído ao volume de armazenamento subjacente pelo gerenciador de montagem. A ID do objeto de volume é atribuída ao volume do sistema de arquivos pelo sistema de arquivos.

Para obter a ID do objeto de volume para um volume, chame ZwQueryVolumeInformationFile, especificando FileFsObjectIdInformation para o parâmetro FsInformationClass.

FltGetVolumeGuidName é aproximadamente equivalente à função GetVolumeNameForVolumeMountPoint do Win32 . (GetVolumeNameForVolumeMountPoint está documentado no SDK do Microsoft Windows.)