UrlCanonicalizeA, fonction (shlwapi.h)

Article
08/26/2023

Convertit une chaîne d’URL en forme canonique.

Syntaxe

LWSTDAPI UrlCanonicalizeA(
  [in]      PCSTR pszUrl,
  [out]     PSTR  pszCanonicalized,
  [in, out] DWORD *pcchCanonicalized,
            DWORD dwFlags
);

Paramètres

[in] pszUrl

Type : PCTSTR

Pointeur vers une chaîne terminée par null de longueur maximale INTERNET_MAX_URL_LENGTH qui contient une chaîne d’URL. Si la chaîne ne fait pas référence à un fichier, elle doit inclure un schéma valide tel que « http:// ».

[out] pszCanonicalized

Type : PTSTR

Pointeur vers une mémoire tampon qui, lorsque cette fonction retourne correctement, reçoit l’URL convertie sous la forme d’une chaîne terminée par null.

[in, out] pcchCanonicalized

Type : DWORD*

Pointeur vers une valeur qui, lors de l’entrée, est défini sur le nombre de caractères dans la mémoire tampon pszCanonicalized .

dwFlags

Type : DWORD

Indicateurs qui spécifient la façon dont l’URL est convertie en forme canonique. Les indicateurs suivants peuvent être combinés.

URL_UNESCAPE (0x10000000)

Supprimez l’échappement des séquences d’échappement que les URL contiennent, à deux exceptions près. Les séquences d’échappement pour « ? » et « # » ne sont pas annulées. Si l’un des indicateurs de URL_ESCAPE_XXX est également défini, les deux URL sont d’abord sans échappement, puis combinées, puis placées dans une séquence d’échappement.

URL_ESCAPE_UNSAFE (0x20000000)

Remplacez les caractères non sécurisés par leurs séquences d’échappement. Les caractères non sécurisés sont les caractères qui peuvent être modifiés pendant le transport sur Internet, et incluent les caractères (<, >, {, }, |, ^, [, ] et '). Cet indicateur s’applique à toutes les URL, y compris aux URL opaques.

URL_PLUGGABLE_PROTOCOL (0x40000000)

Combinez des URL avec des protocoles enfichables définis par le client, conformément à la spécification W3C. Cet indicateur ne s’applique pas à des protocoles standard comme ftp, http, gopher, etc. Si cet indicateur est défini, UrlCombine ne simplifie pas les URL, il n’est donc pas nécessaire de définir également URL_DONT_SIMPLIFY.

URL_ESCAPE_SPACES_ONLY (0x04000000)

Remplacez uniquement les espaces par des séquences d’échappement. Cet indicateur est prioritaire sur URL_ESCAPE_UNSAFE, mais ne s’applique pas aux URL opaques.

URL_DONT_SIMPLIFY (0x08000000)

Traitez « /./ » et « /../ » dans une chaîne d’URL en tant que caractères littéraux et non pas comme un raccourci pour la navigation. Pour en savoir plus, voir Remarques.

URL_NO_META (0x08000000)

Défini pour être identique à URL_DONT_SIMPLIFY.

URL_ESCAPE_PERCENT (0x00001000)

Convertissez toute occurrence de « % » vers sa séquence d’échappement.

URL_ESCAPE_AS_UTF8 (0x00040000)

Windows 7 et versions ultérieures. Encodez en pourcentage tous les caractères non ASCII en tant qu’équivalents UTF-8.

Valeur retournée

Type : HRESULT

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

Remarques

Cette fonction effectue des tâches telles que le remplacement des caractères non sécurisés par leurs séquences d’échappement et l’effondrement des séquences telles que « . ».

Si une chaîne d’URL contient « /.. / » ou « /./ », UrlCanonicalize traite les caractères comme indiquant la navigation dans la hiérarchie d’URL. La fonction simplifie les URL avant de les combiner. Pour instance « /hello/cruel/.. /world » est simplifié en « /hello/world ». Des exceptions à ce comportement par défaut se produisent dans les cas suivants :

Si l’indicateur URL_DONT_SIMPLIFY est défini dans dwFlags, la fonction ne simplifie pas les URL. Dans ce cas, « /hello/cruel/.. /world » est laissé tel qu’il est.
Si « /.. / » ou « /./ » est le premier segment du chemin d’accès (par exemple, « http://domain/../path1/path2/file.htm »), UrlCanonicalize génère le chemin exactement tel qu’il a été entré.

Notes

L’en-tête shlwapi.h définit UrlCanonicalize comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise


Client minimal pris en charge	Windows 2000 Professionnel, Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shlwapi.h
Bibliothèque	Shlwapi.lib
DLL	Shlwapi.dll (version 5.0 ou ultérieure)

Voir aussi

Gestion des localisateurs de ressources uniformes

Partager via