Função PathCchCanonicalize (pathcch.h)

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

Essa função difere de PathCchCanonicalizeEx , na qual você está restrito a um caminho final de comprimento MAX_PATH.

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, PathCchCanonicalizeEx ou PathAllocCanonicalize deve ser usada no lugar de PathCanonicalize para evitar a possibilidade de um estouro de buffer.

Sintaxe

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

Parâmetros

[out] pszPathOut

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

[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 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.

Valor retornado

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código HRESULT , incluindo o 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 excede 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

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

PathCchCanonicalizeEx