Função PathCanonicalizeA (shlwapi.h)

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

Nota O uso indevido dessa função pode levar a um estouro de buffer. Recomendamos o uso da função PathCchCanonicalize ou PathCchCanonicalizeEx mais segura em seu lugar.

 

Sintaxe

BOOL PathCanonicalizeA(
  [out] LPSTR  pszBuf,
  [in]  LPCSTR 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 como 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.

Retornar valor

Tipo: BOOL

Retornará TRUE se um resultado tiver sido calculado 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 é inválido. Para obter informações de erro estendidas, chame GetLastError.

Comentários

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 para 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á TRUE e o conteúdo do buffer apontado por lpszDst conterá 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:\

Observação

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 de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

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