Funzione PathCchCanonicalizeEx (pathcch.h)

Semplifica un percorso rimuovendo gli elementi di spostamento, ad esempio "." e ".." per produrre un percorso diretto e ben formato.

Questa funzione differisce da PathCchCanonicalize in quanto consente di costruire un percorso finale più lungo.

Questa funzione differisce da PathAllocCanonicalize in cui il chiamante deve dichiarare le dimensioni della stringa restituita, archiviata nello stack.

Questa funzione differisce da PathCanonicalize in quanto accetta percorsi con "\", "\?" e "\?\UNC".

Nota Questa funzione, PathCchCanonicalize o PathAllocCanonicalize deve essere usata al posto di PathCanonicalize per evitare la possibilità di un overrun del buffer.

Sintassi

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

Parametri

[out] pszPathOut

Puntatore a un buffer che, quando questa funzione restituisce correttamente, riceve la stringa di percorso modificata.

[in] cchPathOut

Dimensioni del buffer a cui punta pszPathOut, in caratteri.

[in] pszPathIn

Puntatore alla stringa di percorso originale. Se questo valore è NULL, punta a una stringa vuota o genera una stringa vuota dopo la rimozione degli elementi "." e ".". Viene copiata una singola barra rovesciata nel buffer a cui fa riferimento pszPathOut.

[in] dwFlags

Uno o più dei flag seguenti:

Valore	Significato
PATHCCH_NONE 0x0000000	Non consentire la costruzione di percorsi \\?\ (ie, percorsi lunghi) più lunghi di MAX_PATH .
PATHCCH_ALLOW_LONG_PATHS 0x00000001	Consenti la compilazione di percorsi \\?\ più lunghi di MAX_PATH . Si noti che cchPathOut deve essere maggiore di MAX_PATH . In caso contrario, questo flag viene ignorato.
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS 0x00000002	Forza l'API a considerare il chiamante a condizione che il percorso sia abilitato, indipendentemente dallo stato abilitato per il nome lungo del processo. Questa opzione può essere usata solo quando viene specificata PATHCCH_ALLOW_LONG_PATHS e non può essere usata con PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS. Nota Questo valore è disponibile a partire da Windows 10 versione 1703.
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS 0x00000004	Forza l'API a considerare il chiamante a lungo percorso disabilitato, indipendentemente dallo stato abilitato per il nome lungo del processo. Questa opzione può essere usata solo quando viene specificata PATHCCH_ALLOW_LONG_PATHS e non può essere usata con PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS. Nota Questo valore è disponibile a partire da Windows 10 versione 1703.
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS 0x00000008	Disabilita la normalizzazione dei segmenti di percorso che includono la rimozione di punti finali e spazi. Ciò consente l'accesso ai percorsi che la normalizzazione del percorso win32 bloccherà. Nota Questo valore è disponibile a partire da Windows 10 versione 1703.
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH 0x00000010	Converte il percorso di input nel modulo percorso del dispositivo DOS di lunghezza estesa (con il prefisso \\?\) se non già presente in tale formato. Ciò consente l'accesso ai percorsi che altrimenti non sono indirizzabili a causa di regole di normalizzazione Win32 (che possono strisciare punti e spazi finali) e limitazioni della lunghezza del percorso. Questa opzione implica lo stesso comportamento di PATHCCH_DO_NOT_NORMALIZE_SEGMENTS. Nota Questo valore è disponibile a partire da Windows 10 versione 1703.
PATHCCH_ENSURE_TRAILING_SLASH 0x00000020	Quando si combina o normalizza un percorso, assicurarsi che vi sia una barra rovesciata finale. Nota Questo valore è disponibile a partire da Windows 10 versione 1703.

Valore restituito

Se questa funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice HRESULT , incluso ma non limitato ai seguenti.

Codice restituito	Descrizione
E_INVALIDARG	Il valore cchPathOut è maggiore di PATHCCH_MAX_CCH.
PATHCCH_E_FILENAME_TOO_LONG	Un segmento di percorso ha più di PATHCCH_MAX_CCH caratteri oppure, se il flag di PATHCCH_ALLOW_LONG_PATHS non è impostato, supera il limite di lunghezza del segmento di percorso standard di 256 caratteri.
E_OUTOFMEMORY	Impossibile allocare un buffer delle dimensioni necessarie.

Commenti

Questa funzione risponde alle stringhe "." e ".." incorporate in un percorso. La stringa ".." indica la rimozione del segmento di percorso precedente immediatamente. 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 ".." di quanto siano presenti segmenti di percorso, 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 se preceduti dal carattere jolly "". In tal caso, un singolo periodo 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 barra rovesciata (/) in barre indietro (\). Con l'input non attendibile, questa funzione non può essere usata per convertire i percorsi in una maschera che può essere confrontata con altri percorsi per il percorso secondario o l'identità. I chiamanti che necessitano di tale capacità devono convertire in avanti le barre indietro prima di usare questa funzione.

Gli esempi seguenti mostrano 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

Requisito	Valore
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

PathCchCanonicalize