Fonction PathCchCanonicalize (pathcch.h)

Article
08/25/2023

Convertit une chaîne de chemin d’accès en forme canonique.

Cette fonction diffère de PathCchCanonicalizeEx en ce que vous êtes limité à un chemin d’accès final de longueur MAX_PATH.

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 ».

Note Cette fonction PathCchCanonicalizeEx ou PathAllocCanonicalize doit être utilisée à la place de PathCanonicalize pour éviter le risque d’un dépassement de mémoire tampon.

Syntaxe

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

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 canonicalisé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 pointe vers une chaîne vide ou génère une chaîne vide une fois que les éléments « » et « ». » sont supprimés, une seule barre oblique inverse est copiée dans la mémoire tampon pointée par pszPathOut.

Valeur retournée

Si cette fonction réussit, elle retourne S_OK. Sinon, il retourne un code HRESULT , y compris ce qui suit.

Code de retour	Description
E_INVALIDARG	La valeur cchPathOut est supérieure à PATHCCH_MAX_CCH.
PATHCCH_E_FILENAME_TOO_LONG	Un segment de chemin dépasse la limite de longueur de segment de chemin d’accès standard de 256 caractères.
E_OUTOFMEMORY	La fonction n’a pas pu allouer de mémoire tampon de la taille nécessaire.

Notes

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 par pszPathOut contient une seule barre oblique inverse, « \ ».

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:\

Spécifications


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

Voir aussi

PathCchCanonicalizeEx

Partager via