PathCanonicalizeA, fonction (shlwapi.h)

Article
08/26/2023

Simplifie un chemin d’accès en supprimant les éléments de navigation tels que « » et « . » pour produire un chemin d’accès direct et bien formé.

Note Une mauvaise utilisation de cette fonction peut entraîner un dépassement de mémoire tampon. Nous vous recommandons d’utiliser la fonction PathCchCanonicalize ou PathCchCanonicalizeEx plus sûre à sa place.

Syntaxe

BOOL PathCanonicalizeA(
  [out] LPSTR  pszBuf,
  [in]  LPCSTR pszPath
);

Paramètres

[out] pszBuf

Type : LPTSTR

Pointeur vers une chaîne qui reçoit le chemin canonique. Vous devez définir la taille de cette mémoire tampon sur MAX_PATH pour vous assurer qu’elle est suffisamment grande pour contenir la chaîne retournée.

[in] pszPath

Type : LPCTSTR

Pointeur vers une chaîne terminée par null d’une longueur maximale MAX_PATH qui contient le chemin d’accès à canoniser.

Valeur retournée

Type : BOOL

Retourne TRUE si un résultat a été calculé et que le contenu de la mémoire tampon de sortie lpszDst est valide. Retourne FALSE dans le cas contraire, et le contenu de la mémoire tampon pointée par lpszDst n’est pas valide. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Cette fonction permet à l’utilisateur de spécifier ce qu’il faut supprimer d’un chemin en insérant des séquences de caractères spéciales dans le chemin. La séquence .. indique de supprimer un segment de chemin d’accès de la position actuelle vers le segment de chemin d’accès précédent. La séquence « . » indique de passer du segment de chemin suivant au segment de chemin suivant. Impossible de supprimer le segment racine du chemin d’accès.

S’il y a plus de séquences .. que de segments de chemin d’accès, la fonction retourne TRUE et le contenu de la mémoire tampon vers laquelle lpszDst pointe contient uniquement la racine, « ».

Exemples


#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:\

Notes

L’en-tête shlwapi.h définit PathCanonicalize en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel, Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shlwapi.h
Bibliothèque	Shlwapi.lib
DLL	Shlwapi.dll (version 4.71 ou ultérieure)

Partager via