Compartilhar via

Função GetVolumePathNameW (fileapi.h)

  • Artigo

Recupera o ponto de montagem do volume em que o caminho especificado está montado.

Sintaxe

BOOL GetVolumePathNameW(
  [in]  LPCWSTR lpszFileName,
  [out] LPWSTR  lpszVolumePathName,
  [in]  DWORD   cchBufferLength
);

Parâmetros

[in] lpszFileName

Um ponteiro para a cadeia de caracteres de 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 montado 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 arquivo ou nome de 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 Nomenclatura de arquivos, 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 que existe, 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, o valor retornado será C:\; no entanto, se lpszVolumePathName tiver 3 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 que GetFullPathName retorna. 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

Os elementos de caminho à direita inválidos são ignorados. Para caminhos remotos, todo o caminho (não apenas elementos à direita) é 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, se W:\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 o último ponto de junção da cadeia se refere.

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:\.

Exemplos

Para o seguinte conjunto de exemplos, U: é mapeado para o computador \\_YourComputer_\C$remoto e Q é uma unidade local.

Caminho especificado Função retorna
\\_YourComputer_\C$\Windows \\_YourComputer_\C$\
\\?\UNC\_YourComputer_\C$\Windows \\?\UNC\_YourComputer_\C$\
Q:\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 seguinte conjunto de exemplos, os caminhos contêm elementos de caminho à direita inválidos.

Caminho especificado Função retorna
G:\invalid (caminho inválido) G:\
\\.\I:\aaa\invalid (caminho inválido) \\.\I:\
\\_YourComputer_\C$\invalid (elemento 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 fileapi.h (inclua Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também