Funzione PathCanonicalizeW (shlwapi.h)

Articolo
03/02/2024

Semplifica un percorso rimuovendo elementi di spostamento come "." e ".." per produrre un percorso diretto e ben formato.

Nota L'uso improprio di questa funzione può causare un sovraccarico del buffer. È consigliabile usare la funzione PathCchCanonicalize o PathCchCanonicalizeEx più sicura al suo posto.

Sintassi

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

Parametri

[out] pszBuf

Tipo: LPTSTR

Puntatore a una stringa che riceve il percorso canonico. È necessario impostare le dimensioni di questo buffer su MAX_PATH per assicurarsi che sia sufficientemente grande da contenere la stringa restituita.

[in] pszPath

Tipo: LPCTSTR

Puntatore a una stringa con terminazione Null di lunghezza massima MAX_PATH contenente il percorso da canonizzare.

Valore restituito

Tipo: BOOL

Restituisce TRUE se è stato calcolato un risultato e il contenuto del buffer di output lpszDst è valido. Restituisce FALSE in caso contrario e il contenuto del buffer a cui punta lpszDst non è valido. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Questa funzione consente all'utente di specificare cosa rimuovere da un percorso inserendo sequenze di caratteri speciali nel percorso. La sequenza ".." indica di rimuovere un segmento di percorso dalla posizione corrente al segmento di percorso precedente. La sequenza "." indica di ignorare il segmento di percorso successivo al segmento di percorso seguente. Non è possibile rimuovere il segmento radice del percorso.

Se sono presenti più sequenze ".". di quanti siano presenti segmenti di percorso, la funzione restituisce TRUE e il contenuto del buffer a cui punta lpszDst contiene solo la radice "".

Esempi


#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

L'intestazione shlwapi.h definisce PathCanonicalize come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional, Windows XP [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shlwapi.h
Libreria	Shlwapi.lib
DLL	Shlwapi.dll (versione 4.71 o successiva)

Condividi tramite