PathAllocCanonicalize, fonction (pathcch.h)

Article
08/25/2023

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

Cette fonction diffère de PathCchCanonicalize et PathCchCanonicalizeEx en ce qu’elle retourne le résultat sur le tas. Cela signifie que l’appelant n’a pas à déclarer la taille de la chaîne retournée et réduit l’utilisation de la pile.

Cette fonction diffère de PathCanonicalize en ce qu’elle accepte les chemins avec les préfixes « \ », « \ ? » et « \ ?\UNC ».

Note Cette fonction, PathCchCanonicalize ou PathCchCanonicalizeEx, doit être utilisée à la place de PathCanonicalize.

Syntaxe

WINPATHCCHAPI HRESULT PathAllocCanonicalize(
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags,
  [out] PWSTR  *ppszPathOut
);

Paramètres

[in] pszPathIn

Pointeur vers une mémoire tampon qui contient la chaîne d’origine. Cette valeur ne peut pas être NULL.

[in] dwFlags

Un ou plusieurs des indicateurs suivants :

Valeur	Signification
PATHCCH_NONE 0x0000000	N’autorisez pas la construction de chemins \\ ?\ (c’est-à-dire des chemins longs) plus longs que MAX_PATH .
PATHCCH_ALLOW_LONG_PATHS 0x00000001	Autorisez la création de chemins \\ ?\ plus longs que MAX_PATH .
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS 0x00000002	Force l’API à traiter l’appelant comme chemin long activé, indépendamment de l’état de nom long du processus activé. Cette option ne peut être utilisée que lorsque PATHCCH_ALLOW_LONG_PATHS est spécifié et ne peut pas être utilisée avec PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS. Note Cette valeur est disponible à partir de Windows 10, version 1703.
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS 0x00000004	Force l’API à traiter l’appelant comme chemin d’accès long désactivé, indépendamment de l’état activé du nom long du processus. Cette option ne peut être utilisée que lorsque PATHCCH_ALLOW_LONG_PATHS est spécifié et ne peut pas être utilisée avec PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS. Note Cette valeur est disponible à partir de Windows 10, version 1703.
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS 0x00000008	Désactive la normalisation des segments de chemin qui inclut la suppression des points de fin et des espaces. Cela permet d’accéder aux chemins que la normalisation des chemins win32 bloquera. Note Cette valeur est disponible à partir de Windows 10, version 1703.
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH 0x00000010	Convertit le chemin d’entrée dans le formulaire de chemin d’accès de l’appareil DOS de longueur étendue (avec le préfixe \\ ?\) s’il n’est pas déjà dans ce formulaire. Cela permet d’accéder aux chemins qui ne sont autrement pas adressables en raison des règles de normalisation Win32 (qui peuvent supprimer des points et des espaces de fin) et des limitations de longueur de chemin. Cette option implique le même comportement de PATHCCH_DO_NOT_NORMALIZE_SEGMENTS. Note Cette valeur est disponible à partir de Windows 10, version 1703.
PATHCCH_ENSURE_TRAILING_SLASH 0x00000020	Lors de la combinaison ou de la normalisation d’un chemin d’accès, vérifiez qu’il existe une barre oblique inverse de fin. Note Cette valeur est disponible à partir de Windows 10, version 1703.

[out] ppszPathOut

Adresse d’un pointeur vers une mémoire tampon qui, lorsque cette fonction retourne correctement, reçoit la chaîne de chemin d’accès canonique. Il incombe à l’appelant de libérer cette ressource, quand elle n’est plus nécessaire, en appelant la fonction LocalFree . Cette valeur ne peut pas être NULL.

Valeur retournée

Si cette fonction réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.

Remarques

Cette fonction prend en charge ces autres formes de chemin d’accès :

\\?\
\\?\\UNC\
\\ ?\Volume{guid}\

Cette fonction ne convertit pas les barres obliques (/) en barres obliques inverses (\). Avec une entrée non approuvée, cette fonction seule ne peut pas être utilisée pour convertir des chemins 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 fonctionnalité doivent convertir les barres obliques avant en barres obliques inverses avant d’utiliser cette fonction.

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

Partager via