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".
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 |
|---|---|
|
O valor cchPathOut é maior que PATHCCH_MAX_CCH. |
|
Um segmento de caminho excede o limite de comprimento do segmento de caminho padrão de 256 caracteres. |
|
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 |