Compartilhar via

Função PathAllocCanonicalize (pathcch.h)

  • Artigo

Converte uma cadeia de caracteres de caminho em uma forma canônica.

Essa função difere de PathCchCanonicalize e PathCchCanonicalizeEx , pois retorna o resultado no heap. Isso significa que o chamador não precisa declarar o tamanho da cadeia de caracteres retornada e reduz o uso da pilha.

Essa função difere de PathCanonicalize , pois aceita caminhos com prefixos "\", "\?" e "\?\UNC".

Nota Essa função, PathCchCanonicalize ou PathCchCanonicalizeEx, deve ser usada no lugar de PathCanonicalize.

Sintaxe

WINPATHCCHAPI HRESULT PathAllocCanonicalize(
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags,
  [out] PWSTR  *ppszPathOut
);

Parâmetros

[in] pszPathIn

Um ponteiro para um buffer que contém a cadeia de caracteres original. Esse valor não pode ser NULL.

[in] dwFlags

Um ou mais dos seguintes sinalizadores:

Valor Significado
PATHCCH_NONE
0x0000000
 Não permita a construção de caminhos \\?\ (ou seja, caminhos longos) mais longos do que MAX_PATH .
PATHCCH_ALLOW_LONG_PATHS
0x00000001
 Permitir a criação de caminhos \\?\ mais longos do que MAX_PATH .
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS
0x00000002
 Força a API a tratar o chamador como caminho longo habilitado, independentemente do estado habilitado para nome longo do processo. Essa opção só pode ser usada quando PATHCCH_ALLOW_LONG_PATHS é especificado e não pode ser usada com PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS.

Nota Esse valor está disponível a partir do Windows 10, versão 1703.
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS
0x00000004
 Força a API a tratar o chamador como caminho longo desabilitado, independentemente do estado habilitado para nome longo do processo. Essa opção só pode ser usada quando PATHCCH_ALLOW_LONG_PATHS é especificado e não pode ser usada com PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS.

Nota Esse valor está disponível a partir do Windows 10, versão 1703.
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS
0x00000008
 Desabilita a normalização de segmentos de caminho que inclui a remoção de pontos e espaços à direita. Isso permite o acesso a caminhos que a normalização do caminho win32 bloqueará.

Nota Esse valor está disponível a partir do Windows 10, versão 1703.
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH
0x00000010
 Converte o caminho de entrada no formulário de caminho do dispositivo DOS de comprimento estendido (com o prefixo \\?\) se ainda não estiver nesse formulário. Isso permite o acesso a caminhos que, de outra forma, não são endereçáveis devido a regras de normalização do Win32 (que podem remover pontos e espaços à direita) e limitações de comprimento do caminho. Essa opção implica o mesmo comportamento de PATHCCH_DO_NOT_NORMALIZE_SEGMENTS.

Nota Esse valor está disponível a partir do Windows 10, versão 1703.
PATHCCH_ENSURE_TRAILING_SLASH
0x00000020
 Ao combinar ou normalizar um caminho, verifique se há uma barra invertida à direita.

Nota Esse valor está disponível a partir do Windows 10, versão 1703.

[out] ppszPathOut

O endereço de um ponteiro para um buffer que, quando essa função retorna com êxito, recebe a cadeia de caracteres de caminho canônica. É responsabilidade do chamador liberar esse recurso, quando ele não for mais necessário, chamando a função LocalFree . Esse valor não pode ser NULL.

Retornar valor

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Essa função dá suporte a estes formulários de caminho alternativos:

  • \\?\
  • \\?\\UNC\
  • \\?\Volume{guid}\

Essa função não converte barras (/) em barras invertidas (\). Com a entrada não confiável, essa função por si só não pode ser usada para converter caminhos em um formulário que pode ser comparado com outros caminhos para sub-caminho ou identidade. Os chamadores que precisam dessa capacidade devem converter para frente em barras invertidas antes de usar essa função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 8 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho pathcch.h
Biblioteca Pathcch.lib