Função FltGetVolumeGuidName (fltkernel.h)

Artigo
08/07/2023

FltGetVolumeGuidName obtém o nome do volume de um determinado volume, no formato GUID (identificador global exclusivo de 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 pelo chamador.

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

[out, optional] BufferSizeNeeded

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

Retornar valor

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 não NULL para BufferSizeNeeded, FltGetVolumeGuidName armazenará o tamanho do buffer necessário em BufferSizeNeeded. Isso é considerado um código de erro, pois o nome do 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.

Comentários

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 como não NULL. 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 é o 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 posteriores, um driver de minifiltro pode chamar FltGetVolumeGuidName com segurança de sua rotina 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 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 do volume não é o mesmo que a ID do objeto de volume. O GUID do volume, ou 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 de um volume, chame ZwQueryVolumeInformationFile, especificando FileFsObjectIdInformation para o parâmetro FsInformationClass .

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