Funzione PathCchCanonicalize (pathcch.h)

Articolo
08/25/2023

Converte una stringa di percorso in un formato canonico.

Questa funzione differisce da PathCchCanonicalizeEx in quanto è limitato a un percorso finale di lunghezza MAX_PATH.

Questa funzione è diversa da PathAllocCanonicalize in quanto il chiamante deve dichiarare le dimensioni della stringa restituita, archiviata nello stack.

Questa funzione è diversa da PathCanonicalize in quanto accetta i percorsi con prefissi "\", "\?" e "\?\UNC".

Nota Questa funzione , PathCchCanonicalizeEx o PathAllocCanonicalize deve essere usata al posto di PathCanonicalize per evitare il sovraccarico di un buffer.

Sintassi

WINPATHCCHAPI HRESULT PathCchCanonicalize(
  [out] PWSTR  pszPathOut,
  [in]  size_t cchPathOut,
  [in]  PCWSTR pszPathIn
);

Parametri

[out] pszPathOut

Puntatore a un buffer che, quando questa funzione viene restituita correttamente, riceve la stringa di percorso canonica.

[in] cchPathOut

Dimensioni del buffer a cui punta pszPathOut, in caratteri.

[in] pszPathIn

Puntatore alla stringa di percorso originale. Se questo valore punta a una stringa vuota o restituisce una stringa vuota dopo la rimozione degli elementi "." e ".". viene copiata una singola barra rovesciata nel buffer a cui punta pszPathOut.

Valore restituito

Se questa funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice HRESULT , incluso quanto segue.

Codice restituito	Descrizione
E_INVALIDARG	Il valore cchPathOut è maggiore di PATHCCH_MAX_CCH.
PATHCCH_E_FILENAME_TOO_LONG	Un segmento di percorso supera il limite di lunghezza del segmento di percorso standard di 256 caratteri.
E_OUTOFMEMORY	La funzione non è riuscita ad allocare un buffer delle dimensioni necessarie.

Commenti

Questa funzione risponde alle stringhe "." e ".." incorporate in un percorso. La stringa ".." indica di rimuovere il segmento di percorso immediatamente precedente. La stringa "." indica di ignorare il segmento di percorso successivo. Si noti che il segmento radice del percorso non può essere rimosso. Se sono presenti più stringhe ".." rispetto a quelle presenti, la funzione restituisce S_OK e il buffer a cui punta pszPathOut contiene una singola barra rovesciata" "\".

Tutti i periodi finali vengono rimossi dal percorso, tranne quando preceduti dal carattere jolly "". In tal caso, un singolo punto viene mantenuto dopo il carattere '', ma tutti gli altri periodi finali vengono rimossi.

Se il percorso risultante è un'unità radice ("x:"), viene aggiunta una barra rovesciata ("x:\").

Questa funzione non converte le barre (/) in barre rovesciata (\). Con l'input non attendibile, questa funzione non può essere usata per convertire i percorsi in un modulo che può essere confrontato con altri percorsi per il percorso secondario o l'identità. I chiamanti che necessitano di tale capacità devono convertire in avanti in barre rovesciata prima di usare questa funzione.

Negli esempi seguenti viene illustrato l'effetto di queste stringhe.

Stringa originale	Stringa canonica
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:\

Requisiti


Client minimo supportato	Windows 8 [app desktop \| App UWP]
Server minimo supportato	Windows Server 2012 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	pathcch.h
Libreria	Pathcch.lib

Vedi anche

PathCchCanonicalizeEx

Condividi tramite