Função GetShortPathNameW (fileapi.h)

Artigo
03/05/2024

Recupera o formato de caminho curto do caminho especificado.

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

Sintaxe

DWORD GetShortPathNameW(
  [in]  LPCWSTR lpszLongPath,
  [out] LPWSTR  lpszShortPath,
  [in]  DWORD   cchBuffer
);

Parâmetros

[in] lpszLongPath

Cadeia de caracteres de caminho.

Por padrão, o nome é limitado a caracteres MAX_PATH. Para estender esse limite para 32.767 caracteres largos, preencha "\\?\" para o caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.

Dica

A partir do Windows 10, versão 1607, você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima de comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.

[out] lpszShortPath

Um ponteiro para um buffer para receber a forma curta terminada em nulo do caminho que lpszLongPath especifica.

Passar NULL para esse parâmetro e zero para cchBuffer sempre retornará o tamanho do buffer necessário para um lpszLongPath especificado.

[in] cchBuffer

O tamanho do buffer para o qual o lpszShortPath aponta, em TCHARs.

Defina esse parâmetro como zero se lpszShortPath estiver definido como NULL.

Retornar valor

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

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

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

Comentários

O caminho que o parâmetro lpszLongPath especifica não precisa ser um caminho completo ou longo. O formulário curto pode ser maior que o caminho especificado.

Se o valor retornado for maior que o valor especificado no parâmetro cchBuffer , você poderá chamar a função novamente com um buffer grande o suficiente para manter o caminho. Para obter um exemplo desse caso, além de usar o buffer de comprimento zero para alocação dinâmica, consulte a seção Código de Exemplo.

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.

Se o caminho especificado já estiver em sua forma curta e a conversão não for necessária, a função simplesmente copiará o caminho especificado para o buffer especificado pelo parâmetro lpszShortPath .

Você pode definir o parâmetro lpszShortPath com o mesmo valor que o parâmetro lpszLongPath ; em outras palavras, você pode definir o buffer de saída do caminho curto para o endereço da cadeia de caracteres de caminho de entrada. Sempre verifique se o parâmetro cchBuffer representa com precisão o tamanho total, em TCHARs, desse buffer.

Você pode obter o nome longo de um arquivo do nome curto chamando a função GetLongPathName . Como alternativa, em que GetLongPathName não está disponível, você pode chamar FindFirstFile em cada componente do caminho para obter o nome longo correspondente.

É 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, GetShortPathName pode falhar quando não for possível consultar o diretório pai de um componente de caminho para determinar o nome curto desse componente. Esse marcar pode ser ignorado para componentes de diretório que já atendem aos requisitos de um nome curto. 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	No
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	No
Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS)	No
ReFS (Sistema de Arquivos Resiliente)	Sim

O SMB 3.0 não dá suporte a nomes curtos em compartilhamentos com funcionalidade de disponibilidade contínua.

O ReFS (Sistema de Arquivos Resiliente) não dá suporte a nomes curtos. Se você chamar GetShortPathName em um caminho que não tenha nomes curtos em disco, a chamada terá êxito, mas retornará o caminho de nome longo. Esse resultado também é possível com volumes NTFS porque não há garantia de que um nome curto existirá para um determinado nome longo.

Exemplos

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

O exemplo do C++ a seguir mostra como usar um buffer de saída alocado dinamicamente.

//...
    long     length = 0;
    TCHAR*   buffer = NULL;

// First obtain the size needed by passing NULL and 0.

    length = GetShortPathName(lpszPath, NULL, 0);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

// Dynamically allocate the correct size 
// (terminating null char was included in length)

    buffer = new TCHAR[length];

// Now simply call again using same long path.

    length = GetShortPathName(lpszPath, buffer, length);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

    _tprintf(TEXT("long name = %s shortname = %s"), lpszPath, buffer);
    
    delete [] buffer;
///...

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