Função PathCchCanonicalizeEx (pathcch.h)

  • Artigo

Simplifica um caminho removendo elementos de navegação como "." e "." para produzir um caminho direto e bem formado.

Essa função difere de PathCchCanonicalize , pois permite que um caminho final mais longo seja construído.

Essa função difere de PathAllocCanonicalize porque o chamador deve declarar o tamanho da cadeia de caracteres retornada, que é armazenada na pilha.

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

Nota Essa função, PathCchCanonicalize ou PathAllocCanonicalize deve ser usada no lugar de PathCanonicalize para evitar a possibilidade de um estouro de buffer.

Sintaxe

WINPATHCCHAPI HRESULT PathCchCanonicalizeEx(
  [out] PWSTR  pszPathOut,
  [in]  size_t cchPathOut,
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags
);

Parâmetros

[out] pszPathOut

Um ponteiro para um buffer que, quando essa função retorna com êxito, recebe a cadeia de caracteres de caminho editada.

[in] cchPathOut

O tamanho do buffer apontado por pszPathOut, em caracteres.

[in] pszPathIn

Um ponteiro para a cadeia de caracteres de caminho original. Se esse valor for NULL, apontará para uma cadeia de caracteres vazia ou resultará em uma cadeia de caracteres vazia depois que os elementos "." e ".." forem removidos, uma única barra invertida será copiada para o buffer apontado por pszPathOut.

[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 . Observe que cchPathOut deve ser maior que MAX_PATH . Se não for, esse sinalizador será ignorado.
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 podem ser 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.

Retornar valor

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código HRESULT , incluindo, mas não se limitando ao seguinte.

Código de retorno Descrição
E_INVALIDARG
 O valor cchPathOut é maior que PATHCCH_MAX_CCH.
PATHCCH_E_FILENAME_TOO_LONG
 Um segmento de caminho tem mais de PATHCCH_MAX_CCH caracteres ou, se o sinalizador PATHCCH_ALLOW_LONG_PATHS não estiver definido, excederá o limite de comprimento do segmento de caminho padrão de 256 caracteres.
E_OUTOFMEMORY
 A função não pôde alocar um buffer do tamanho necessário.

Comentários

Essa função responde às cadeias de caracteres "." e "." inseridas em um caminho. A cadeia de caracteres ".." indica para remover o segmento de caminho imediatamente anterior. A cadeia de caracteres "." indica ignorar o próximo segmento de caminho. Observe que o segmento raiz do caminho não pode ser removido. Se houver mais cadeias de caracteres ".." do que segmentos de caminho, a função retornará S_OK e o buffer apontado por pszPathOut conterá uma única barra invertida, "\".

Todos os períodos à direita são removidos do caminho, exceto quando precedidos pelo caractere de cartão selvagem "". Nesse caso, um único período é mantido após o caractere '', mas todos os outros períodos à direita são removidos.

Se o caminho resultante for uma unidade raiz ("x:"), uma barra invertida será acrescentada ("x:\").

Essa função não converte barras (/) em barras traseiras (\). 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 traseiras antes de usar essa função.

Os exemplos a seguir mostram o efeito dessas cadeias de caracteres.

Cadeia de caracteres original Cadeia de caracteres canônica
C:\name_1\.\name_2\.. \name_3 C:\name_1\name_3
C:\name_1\.. \name_2\.\name_3 C:\name_2\name_3
C:\name_1\name_2\.\name_3\.. \name_4 C:\name_1\name_2\name_4
C:\name_1\.\name_2\.\name_3\.. \name_4\.. C:\name_1\name_2
C:\name_1\*... C:\name_1\*.
C:\.. C:\

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

Confira também

PathCchCanonicalize