UrlCanonicalizeW, fonction (shlwapi.h)
Convertit une chaîne d’URL sous forme canonique.
Syntaxe
LWSTDAPI UrlCanonicalizeW(
[in] PCWSTR pszUrl,
[out] PWSTR 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 en tant que 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)
Annulez l’échappement des séquences d’échappement que les URL contiennent, avec deux exceptions. Les séquences d’échappement pour « ? » et « # » ne sont pas sans échappement. Si l’un des indicateurs URL_ESCAPE_XXX est également défini, les deux URL sont d’abord non échappées, puis combinées, puis échappées.
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 ceux 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 les 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 aux protocoles standard tels que 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 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, pas comme raccourci pour la navigation. Pour plus d’informations, consultez les remarques.
URL_NO_META (0x08000000)
Défini comme étant identique à URL_DONT_SIMPLIFY.
URL_ESCAPE_PERCENT (0x00001000)
Convertissez toute occurrence de «%» en 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 de retour
Type : HRESULT
Si cette fonction réussit, elle retourne S_OK. Sinon, elle retourne un HRESULT code d’erreur.
Remarques
Cette fonction effectue des tâches telles que le remplacement de caractères non sécurisés par leurs séquences d’échappement et la réduction des séquences comme « ..... ».
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. Par exemple « /hello/cruel/.. /world » est simplifié en « /hello/world ». Les 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é comme c’est le cas.
- 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 comme il était entrée.
Note
L’en-tête shlwapi.h définit UrlCanonicalize en tant qu’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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 2000 Professionnel, Windows XP [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | shlwapi.h |
| bibliothèque | Shlwapi.lib |
| DLL | Shlwapi.dll (version 5.0 ou ultérieure) |