Função GetLongPathNameA (fileapi.h)

Artigo
03/05/2024

Converte o caminho especificado em seu formato longo.

Para executar essa operação como uma operação transacionada, use a função GetLongPathNameTransacted .

Para obter mais informações sobre nomes de arquivo e caminho, consulte Nomenclatura de arquivos, caminhos e namespaces.

Sintaxe

DWORD GetLongPathNameA(
  [in]  LPCSTR lpszShortPath,
  [out] LPSTR  lpszLongPath,
  [in]  DWORD  cchBuffer
);

Parâmetros

[in] lpszShortPath

O caminho a ser convertido.

[out] lpszLongPath

Um ponteiro para o buffer para receber o caminho longo.

Você pode usar o mesmo buffer usado para o parâmetro lpszShortPath .

[in] cchBuffer

O tamanho do buffer lpszLongPath aponta para, em TCHARs.

Retornar valor

Se a função for bem-sucedida, o valor retornado será o comprimento, em TCHARs, da cadeia de caracteres copiada para lpszLongPath, sem incluir o caractere nulo de terminação.

Se o buffer lpBuffer for muito pequeno para conter o caminho, o valor retornado será o tamanho, em TCHARs, do buffer necessário para manter o caminho e o caractere nulo de terminação.

Se a função falhar por qualquer outro motivo, como se o arquivo não existir, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Em muitos sistemas de arquivos, um nome de arquivo curto contém um caractere de bloco (~). No entanto, nem todos os sistemas de arquivos seguem essa convenção. Portanto, não suponha que você possa ignorar a chamada GetLongPathName se o caminho não contiver um caractere de bloco (~).

Se o arquivo ou diretório existir, mas um caminho longo não for encontrado, GetLongPathName terá êxito, tendo copiado a cadeia de caracteres referenciada pelo parâmetro lpszShortPath para o buffer referenciado pelo parâmetro lpszLongPath .

Se o valor retornado for maior que o valor especificado em cchBuffer, você poderá chamar a função novamente com um buffer grande o suficiente para manter o caminho. Para obter um exemplo desse caso, consulte a seção Código de Exemplo para GetFullPathName.

Nota Embora o valor retornado nesse caso seja um comprimento que inclui o caractere nulo de terminação, o valor retornado com êxito não inclui o caractere nulo de terminação na contagem.

É possível ter acesso a um arquivo ou diretório, mas não ter acesso a alguns dos diretórios pai desse arquivo ou diretório. Como resultado, GetLongPathName pode falhar quando não for possível consultar o diretório pai de um componente de caminho para determinar o nome longo desse componente. Essa marcar pode ser ignorada para componentes de diretório que têm extensões de arquivo com mais de 3 caracteres ou comprimentos totais com mais de 12 caracteres. Para obter mais informações, consulte a seção Nomes curtos versus longos de Arquivos de Nomenclatura, Caminhos e Namespaces.

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	Sim
TFO (Failover transparente) do SMB 3.0	Sim
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	Sim
Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

Exemplos

Para obter um exemplo que usa GetLongPathName, consulte a seção Código de Exemplo para GetFullPathName.

Observação

O cabeçalho fileapi.h define GetLongPathName como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	fileapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll