Fonction InternetCanonicalizeUrlW (wininet.h)

Article
03/13/2024

Canonique une URL, qui inclut la conversion de caractères et d’espaces non sécurisés en séquences d’échappement.

Syntaxe

BOOL InternetCanonicalizeUrlW(
  [in]      LPCWSTR lpszUrl,
  [out]     LPWSTR  lpszBuffer,
  [in, out] LPDWORD lpdwBufferLength,
  [in]      DWORD   dwFlags
);

Paramètres

[in] lpszUrl

Pointeur vers la chaîne qui contient l’URL à canoniser.

[out] lpszBuffer

Pointeur vers la mémoire tampon qui reçoit l’URL canonique résultante.

[in, out] lpdwBufferLength

Pointeur vers une variable qui contient la taille, en caractères, de la mémoire tampon lpszBuffer . Si la fonction réussit, ce paramètre reçoit le nombre de caractères réellement copiés dans la mémoire tampon lpszBuffer , qui n’inclut pas le caractère null de fin. Si la fonction échoue, ce paramètre reçoit la taille requise de la mémoire tampon, en caractères, qui inclut le caractère null de fin.

[in] dwFlags

Contrôle la canonisation. Si aucun indicateur n’est spécifié, la fonction convertit tous les caractères non sécurisés et les séquences de métadonnées (telles que .,\.., et ...) en séquences d’échappement. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
ICU_BROWSER_MODE	N’encode pas ni ne décode les caractères après « # » ou « ? », et ne supprime pas les espaces blancs de fin après « ? ». Si cette valeur n’est pas spécifiée, l’URL entière est encodée et l’espace blanc de fin est supprimé.
ICU_DECODE	Convertit toutes les séquences %XX en caractères, y compris les séquences d’échappement, avant l’analyse de l’URL.
ICU_ENCODE_PERCENT	Encode tous les signes de pourcentage rencontrés. Par défaut, les signes de pourcentage ne sont pas encodés. Cette valeur est disponible dans Microsoft Internet Explorer 5 et versions ultérieures.
ICU_ENCODE_SPACES_ONLY	Encode uniquement les espaces.
ICU_NO_ENCODE	Ne convertit pas les caractères non sécurisés en séquences d’échappement.
ICU_NO_META	Ne supprime pas les séquences de métadonnées (telles que « » et « . . ») de l’URL.

Valeur retournée

Retourne TRUE en cas de réussite, ou FALSE dans le cas contraire. Pour obtenir des informations détaillées sur l’erreur, appelez la fonction GetLastError. Les erreurs possibles sont les suivantes.

Code de retour	Description
ERROR_BAD_PATHNAME	L’URL n’a pas pu être canonique.
ERROR_INSUFFICIENT_BUFFER	L’URL canonique est trop grande pour tenir dans la mémoire tampon fournie. Le paramètre lpdwBufferLength est défini sur la taille, en octets, de la mémoire tampon requise pour contenir l’URL canonique.
ERROR_INTERNET_INVALID_URL	Le format de l’URL n’est pas valide.
ERROR_INVALID_PARAMETER	Il existe un paramètre de chaîne, de mémoire tampon, de taille de mémoire tampon ou d’indicateur non valide.

Remarques

Dans Internet Explorer 4.0 et versions ultérieures, InternetCanonicalizeUrl fonctionne toujours comme si l’indicateur ICU_BROWSER_MODE était défini. Les applications clientes qui doivent canoniser l’URL entière doivent utiliser CoInternetParseUrl (avec l’action PARSE_CANONICALIZE et l’indicateur URL_ESCAPE_UNSAFE) ou UrlCanonicalize.

InternetCanonicalizeUrl encode toujours par défaut, même si l’indicateur ICU_DECODE a été spécifié. Pour décoder sans recodage, utilisez ICU_DECODE | ICU_NO_ENCODE. Si l’indicateur ICU_DECODE est utilisé sans ICU_NO_ENCODE, l’URL est décodée avant d’être analysée ; Les caractères non sécurisés sont ensuite réencodés après l’analyse. Cette fonction gère des schémas de protocole arbitraires, mais pour ce faire, elle doit effectuer des inférences à partir du jeu de caractères non sécurisé.

Les applications qui appellent InternetCanonicalizeUrl lors de l’utilisation d’Internet Explorer 3.0 (ou lors de la définition de l’indicateur de ICU_ENCODE_PERCENT pour Internet Explorer 5 et versions ultérieures) doivent suivre l’utilisation de cette fonction sur une URL particulière. Si des caractères non sécurisés dans une URL ont été convertis en séquences d’échappement, l’utilisation d’InternetCanonicalizeUrl à nouveau sur l’URL (sans indicateur) entraîne la conversion des séquences d’échappement en une autre séquence d’échappement. Par exemple, un espace vide dans une URL est converti en séquence d’échappement %20. L’appel d’InternetCanonicalizeUrl à nouveau sur l’URL entraîne la conversion de la séquence d’échappement %20 en séquence d’échappement %2520, car le signe % est un caractère non sécurisé réservé aux séquences d’échappement et remplacé par la fonction par la séquence d’échappement %25.

Comme tous les autres aspects de l’API WinINet, cette fonction ne peut pas être appelée en toute sécurité à partir de DllMain ou des constructeurs et destructeurs d’objets globaux.

Note WinINet ne prend pas en charge les implémentations de serveur. En outre, il ne doit pas être utilisé à partir d’un service. Pour les implémentations de serveur ou les services, utilisez Microsoft Windows HTTP Services (WinHTTP).

Notes

L’en-tête wininet.h définit InternetCanonicalizeUrl 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. La combinaison 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

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wininet.h
Bibliothèque	Wininet.lib
DLL	Wininet.dll

Voir aussi

Gestion des localisateurs de ressources uniformes

Fonctions WinINet

Partager via