Fonction PathCchCanonicalizeEx (pathcch.h)
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é.
Cette fonction diffère de PathCchCanonicalize en ce qu’elle permet de construire un chemin final plus long.
Cette fonction diffère de PathAllocCanonicalize en ce que l’appelant doit déclarer la taille de la chaîne retournée, qui est stockée sur la pile.
Cette fonction diffère de PathCanonicalize en ce qu’elle accepte les chemins d’accès avec les préfixes « \ », « \ ? » et « \ ?\UNC ».
Syntaxe
WINPATHCCHAPI HRESULT PathCchCanonicalizeEx(
[out] PWSTR pszPathOut,
[in] size_t cchPathOut,
[in] PCWSTR pszPathIn,
[in] ULONG dwFlags
);
Paramètres
[out] pszPathOut
Pointeur vers une mémoire tampon qui, lorsque cette fonction retourne correctement, reçoit la chaîne de chemin d’accès modifiée.
[in] cchPathOut
Taille de la mémoire tampon pointée vers pszPathOut, en caractères.
[in] pszPathIn
Pointeur vers la chaîne de chemin d’accès d’origine. Si cette valeur a la valeur NULL, pointe vers une chaîne vide ou donne lieu à une chaîne vide une fois que les éléments « » et « ». » ont été supprimés, une seule barre oblique inverse est copiée dans la mémoire tampon pointée par pszPathOut.
[in] dwFlags
Un ou plusieurs des indicateurs suivants :
Valeur retournée
Si cette fonction réussit, elle retourne S_OK. Sinon, il retourne un code HRESULT , y compris, mais sans s’y limiter, les éléments suivants.
| Code de retour | Description |
|---|---|
|
La valeur cchPathOut est supérieure à PATHCCH_MAX_CCH. |
|
Un segment de chemin comporte plus de PATHCCH_MAX_CCH caractères ou, si l’indicateur de PATHCCH_ALLOW_LONG_PATHS n’est pas défini, dépasse la limite de longueur de segment de chemin d’accès standard de 256 caractères. |
|
La fonction n’a pas pu allouer de mémoire tampon de la taille nécessaire. |
Remarques
Cette fonction répond aux chaînes « » et « . ». incorporées dans un chemin d’accès. La chaîne .. » indique de supprimer le segment de chemin d’accès qui précède immédiatement. La chaîne « ». indique d’ignorer le segment de chemin d’accès suivant. Notez que le segment racine du chemin d’accès ne peut pas être supprimé. S’il y a plus de chaînes « ». que de segments de chemin d’accès, la fonction retourne S_OK et la mémoire tampon pointée vers pszPathOut contient une barre oblique inverse unique, « \ ».
Toutes les périodes de fin sont supprimées du chemin, sauf lorsqu’elles sont précédées du caractère « » carte générique. Dans ce cas, un point unique est conservé après le caractère « », mais toutes les autres périodes de fin sont supprimées.
Si le chemin d’accès résultant est un lecteur racine (« x : »), une barre oblique inverse est ajoutée (« x :\ »).
Cette fonction ne convertit pas les barres obliques (/) en barres obliques arrière (\). Avec une entrée non approuvée, cette fonction en elle-même ne peut pas être utilisée pour convertir des chemins d’accès en un formulaire qui peut être comparé à d’autres chemins d’accès pour le sous-chemin ou l’identité. Les appelants qui ont besoin de cette capacité doivent convertir des barres obliques en barres obliques arrière avant d’utiliser cette fonction.
Les exemples suivants illustrent l’effet de ces chaînes.
| Chaîne d’origine | Chaîne canonisée |
|---|---|
| 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:\ |
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 8 [applications de bureau | Applications UWP] |
| Serveur minimal pris en charge | Windows Server 2012 [applications de bureau | Applications UWP] |
| Plateforme cible | Windows |
| En-tête | pathcch.h |
| Bibliothèque | Pathcch.lib |