Função PathCanonicalizeW (shlwapi.h)

Artigo
11/20/2024

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

Observação Uso indevido dessa função pode levar a uma sobrecarga de buffer. Recomendamos o uso da função PathCchCanonicalize ou PathCchCanonicalizeEx em seu lugar.

Sintaxe

BOOL PathCanonicalizeW(
  [out] LPWSTR  pszBuf,
  [in]  LPCWSTR pszPath
);

Parâmetros

[out] pszBuf

Tipo: LPTSTR

Um ponteiro para uma cadeia de caracteres que recebe o caminho canônico. Você deve definir o tamanho desse buffer para MAX_PATH para garantir que ele seja grande o suficiente para manter a cadeia de caracteres retornada.

[in] pszPath

Tipo: LPCTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo de comprimento máximo MAX_PATH que contém o caminho a ser canonizado.

Valor de retorno

Tipo: BOOL

Retorna verdadeiro se um resultado tiver sido computado e o conteúdo do buffer de saída lpszDst for válido. Retorna false caso contrário, e o conteúdo do buffer apontado por lpszDst são inválidos. Para obter informações de erro estendidas, chame GetLastError.

Observações

Essa função permite que o usuário especifique o que remover de um caminho inserindo sequências de caracteres especiais no caminho. A sequência ".." indica remover um segmento de caminho da posição atual para o segmento de caminho anterior. A sequência "." indica ignorar o próximo segmento de caminho para o segmento de caminho a seguir. O segmento raiz do caminho não pode ser removido.

Se houver mais sequências ".." do que segmentos de caminho, a função retornará verdadeiro e o conteúdo do buffer apontado por lpszDst contém apenas a raiz, "".

Exemplos


#include <windows.h>
#include <iostream>
#include "Shlwapi.h"

using namespace std;

int main( void )
{
// Path_1 destination buffer.
char buffer_1[MAX_PATH] = "JustABufferToHoldTheCanonicalizedPathForAnExample";
char *lpStr1;
lpStr1 = buffer_1;

// Path_2 to be Canonicalized.
char buffer_2[ ] = "A:\\name_1\\.\\name_2\\..\\name_3";
char *lpStr2;
lpStr2 = buffer_2;

// Path_3 to be Canonicalized.
char buffer_3[ ] = "A:\\name_1\\..\\name_2\\.\\name_3";
char *lpStr3;
lpStr3 = buffer_3;

// Path_4 to be Canonicalized.
char buffer_4[ ] = "A:\\name_1\\name_2\\.\\name_3\\..\\name_4";
char *lpStr4;
lpStr4 = buffer_4;

// Path_5 to be Canonicalized.
char buffer_5[ ] = "A:\\name_1\\.\\name_2\\.\\name_3\\..\\name_4\\..";
char *lpStr5;
lpStr5 = buffer_5;

// Path_6 to be Canonicalized.
char buffer_6[ ] = "C:\\..";
char *lpStr6;
lpStr6 = buffer_6;

cout << "The un-canonicalized path 2 is : " << lpStr2
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr2)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 3 is : " << lpStr3
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr3)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 4 is : " << lpStr4
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr4)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 5 is : " << lpStr5
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr5) 
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 6 is : " << lpStr6
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr6)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;
}
OUTPUT:
---------
The un-canonicalized path 2 is : A:\name_1\.\name_2\..\name_3
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_3

The un-canonicalized path 3 is : A:\name_1\..\name_2\.\name_3
The return value is            : 1
The canonicalized path 1 is    : A:\name_2\name_3

The un-canonicalized path 4 is : A:\name_1\name_2\.\name_3\..\name_4
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_2\name_4

The un-canonicalized path 5 is : A:\name_1\.\name_2\.\name_3\..\name_4\..
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_2

The un-canonicalized path 6 is : C:\..
The return value is            : 1
The canonicalized path 1 is    : C:\

Nota

O cabeçalho shlwapi.h define PathCanonicalize como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional, Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	shlwapi.h
biblioteca	Shlwapi.lib
de DLL	Shlwapi.dll (versão 4.71 ou posterior)

Compartilhar via