Função GetVolumePathNameA (winbase.h)
Recupera o ponto de montagem do volume em que o caminho especificado está montado.
Sintaxe
BOOL GetVolumePathNameA(
[in] LPCSTR lpszFileName,
[out] LPSTR lpszVolumePathName,
[in] DWORD cchBufferLength
);
Parâmetros
[in] lpszFileName
Um ponteiro para a cadeia de caracteres do caminho de entrada. Nomes de arquivo e diretório absolutos e relativos, por exemplo "..", são aceitáveis nesse caminho.
Se você especificar um diretório relativo ou um nome de arquivo sem um qualificador de volume, GetVolumePathName retornará a letra da unidade do volume de inicialização.
Se esse parâmetro for uma cadeia de caracteres vazia, "", a função falhará, mas o último erro será definido como ERROR_SUCCESS.
[out] lpszVolumePathName
Um ponteiro para uma cadeia de caracteres que recebe o ponto de montagem de volume para o caminho de entrada.
[in] cchBufferLength
O comprimento do buffer de saída, em TCHARs.
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Comentários
Se um caminho especificado for passado, GetVolumePathName retornará o caminho para o ponto de montagem do volume, o que significa que ele retorna a raiz do volume em que o ponto final do caminho especificado está localizado.
Por exemplo, suponha que você tenha o volume D montado em C:\Mnt\Ddrive e o volume E montados em "C:\Mnt\Ddrive\Mnt\Edrive". Suponha também que você tenha um arquivo com o caminho "E:\Dir\Subdir\MyFile". Se você passar "C:\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFile" para GetVolumePathName, ele retornará o caminho "C:\Mnt\Ddrive\Mnt\Edrive".
Se um diretório relativo ou um arquivo for passado sem um qualificador de volume, a função retornará a letra da unidade do volume de inicialização. A letra da unidade do volume de inicialização também será retornada se um arquivo ou nome de diretório inválido for especificado sem um qualificador de volume válido. Se um especificador de volume válido for fornecido e o volume existir, mas um nome de arquivo ou diretório inválido for especificado, a função terá êxito e esse nome de volume será retornado. Para obter exemplos, consulte a seção Exemplos deste tópico.
Você deve especificar um caminho de namespace win32 válido. Se você especificar um caminho de namespace NT, por exemplo, "\DosDevices\H:" ou "\Device\HardDiskVolume6", a função retornará a letra da unidade do volume de inicialização, não a letra da unidade desse caminho de namespace NT.
Para obter mais informações sobre nomes de caminho e namespaces, consulte Arquivos de nomenclatura, caminhos e namespaces.
Você pode especificar caminhos locais e remotos. Se você especificar um caminho local, GetVolumePathName retornará um caminho completo cujo prefixo é o prefixo mais longo que representa um volume.
Se um compartilhamento de rede for especificado, GetVolumePathName retornará o caminho mais curto para o qual GetDriveType retorna DRIVE_REMOTE, o que significa que o caminho é validado como uma unidade remota existente, que o usuário atual pode acessar.
Há certos casos especiais que não retornam uma barra invertida à direita. Elas ocorrem quando o comprimento do buffer de saída é um caractere muito curto. Por exemplo, se lpszFileName for C: e lpszVolumePathName tiver 4 caracteres de comprimento, o valor retornado será "C:"; no entanto, se lpszVolumePathName tiver três caracteres, o valor retornado será "C:". Uma maneira mais segura, mas mais lenta de definir o tamanho do buffer de retorno é chamar a função GetFullPathName e verificar se o tamanho do buffer tem pelo menos o mesmo tamanho que o caminho completo retornado por GetFullPathName . Se o buffer de saída for mais de um caractere muito curto, a função falhará e retornará um erro.
No Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.
| Tecnologia | Com suporte |
|---|---|
| Protocolo SMB (SMB) 3.0 | No |
| TFO (Failover transparente) do SMB 3.0 | No |
| SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | No |
| Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS) | Sim |
| ReFS (Sistema de Arquivos Resiliente) | Sim |
O SMB não dá suporte a funções de gerenciamento de volume.
Elementos de caminho à direita
Elementos de caminho à direita inválidos são ignorados. Para caminhos remotos, todo o caminho (não apenas elementos à direita) será considerado inválido se uma das seguintes condições for verdadeira:- O caminho não está formado corretamente.
- O caminho não existe.
- O usuário atual não tem acesso ao caminho.
Pontos de junção e pastas montadas
Se o caminho especificado percorrer um ponto de junção, GetVolumePathName retornará o volume ao qual o ponto de junção se refere. Por exemplo, seW:\Adir for um ponto de junção que aponta para C:\Adir, GetVolumePathName invocado em W:\Adir\Afile retornará "C:\".
Se o caminho especificado percorrer vários pontos de junção, toda a cadeia será seguida e GetVolumePathName retornará o volume ao qual se refere o último ponto de junção na cadeia.
Se um caminho remoto para uma pasta montada ou ponto de junção for especificado, o caminho será analisado como um caminho remoto e a pasta montada ou o ponto de junção serão ignorados. Por exemplo, se C:\Dir_C estiver vinculado a D:\Dir_D e C: for mapeado para X: em um computador remoto, chamar GetVolumePathName e especificar X:\Dir_C no computador remoto retornará X:</code>.
Exemplos
Para o seguinte conjunto de exemplos, U: é mapeado para o computador remoto \\YourComputer\C$, e Q é uma unidade local.
Caminho especificado
Retorna função
\\YourComputer\C$\Windows
\\YourComputer\C$\
\\?\UNC\YourComputer\C$\Windows
\\?\UNC\YourComputer\C$\
P:\Windows
Q:\
\\?\Q:\Windows
\\?\Q:\
\\.\Q:\Windows
\\.\Q:\
\\?\UNC\W:\Windows
FALSE com o erro 123 porque um caminho remoto especificado não era válido; O compartilhamento W$ não existe ou nenhum acesso de usuário concedido.
C:\COM2 (que existe)
\\.\COM2\
C:\COM3 (inexistente)
FALSE com o erro 123 porque um dispositivo COM inexistente foi especificado.
Para o conjunto de exemplos a seguir, os caminhos contêm elementos de caminho à direita inválidos.
Caminho especificado
Retorna função
G:\invalid (caminho inválido)
G:\
\\.\I:\aaa\invalid (caminho inválido)
\\.\Eu:\
\\YourComputer\C$\invalid (elemento de caminho à direita inválido)
\\YourComputer\C$\
Requisitos
Requisito
Valor
Cliente mínimo com suporte
Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte
Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino
Windows
Cabeçalho
winbase.h (inclua Windows.h)
Biblioteca
Kernel32.lib
DLL
Kernel32.dll
Confira também
GetVolumeNameForVolumeMountPoint
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de