Funzione PathCchCombineEx (pathcch.h)

Articolo
03/05/2024

Combina due frammenti di percorso in un singolo percorso. Questa funzione canonizza anche gli elementi del percorso relativi, rimuovendo "." e ".." per semplificare il percorso finale.

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

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

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

Nota Questa funzione, PathCchCombine o PathAllocCombine deve essere usata al posto di PathCombine per evitare la possibilità di un overrun del buffer.

Sintassi

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

Parametri

[out] pszPathOut

Puntatore a un buffer che, quando questa funzione restituisce correttamente, riceve la stringa di percorso combinata. Questo parametro può puntare allo stesso buffer di pszPathIn o pszMore.

[in] cchPathOut

Dimensioni del buffer a cui punta pszPathOut, in caratteri.

[in, optional] pszPathIn

Puntatore alla prima stringa di percorso. Questo valore può essere NULL.

[in, optional] pszMore

Puntatore alla seconda stringa di percorso. Se questo percorso inizia con una singola barra rovesciata, viene combinato con solo la radice del percorso a cui fa riferimento pszPathIn. Se questo percorso è completo, viene copiato direttamente nel buffer di output senza essere combinato con l'altro percorso. Questo valore può essere NULL.

[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 costruzione 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.

Valore restituito

Questa funzione restituisce un codice HRESULT , incluso quanto segue.

Codice restituito	Descrizione
S_OK	Funzione completata. Si noti che questo include anche il caso di un'estensione vuota, ad esempio un punto senza caratteri che lo seguono. In tal caso, la stringa originale viene restituita invariata.
E_INVALIDARG	Questo valore può essere causato da diverse cose, ad esempio il param pszPathOut impostato su NULL o il valore cchPathOut impostato su 0 o un valore maggiore di PATHCCH_MAX_CCH .
E_OUTOFMEMORY	La funzione non ha potuto allocare memoria sufficiente per eseguire l'operazione.
PATHCCH_E_FILENAME_TOO_LONG	Le dimensioni di uno o entrambi i percorsi originali superano PATHCCH_MAX_CCH .

Commenti

Se sia pszPathIn che pszMore sono NULL o puntano a stringhe vuote, una singola barra rovesciata viene copiata nel buffer a cui fa riferimento pszPathOut.

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

PathCchCanonicalizeEx

PathCchCombine

Condividi tramite