InternetCanonicalizeUrlA, fonction (wininet.h)

Article
11/20/2024

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

Syntaxe

BOOL InternetCanonicalizeUrlA(
  [in]      LPCSTR  lpszUrl,
  [out]     LPSTR   lpszBuffer,
  [in, out] LPDWORD lpdwBufferLength,
  [in]      DWORD   dwFlags
);

Paramètres

[in] lpszUrl

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

[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, ce 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, ce 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 et séquences meta non sécurisés (tels que .,\.., et ...) en séquences d’échappement. Ce paramètre peut être l’une des valeurs suivantes.

Valeur	Signification
ICU_BROWSER_MODE	N’encode pas ou ne décode pas les caractères après « # » ou « ? », et ne supprime pas l’espace blanc 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 les espaces uniquement.
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 méta (telles que « » et « . . ») de l’URL.

Valeur de retour

Retourne TRUE en cas de réussite ou FALSE sinon. Pour obtenir des informations d’erreur étendues, appelez la fonction GetLastError. Les erreurs possibles sont les suivantes.

Retourner le code	Description
ERROR_BAD_PATHNAME	L’URL n’a pas pu être canonique.
ERROR_INSUFFICIENT_BUFFER	L’URL canonique est trop grande pour s’adapter à 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 une chaîne, une mémoire tampon, une taille de mémoire tampon ou un paramètre d’indicateur non valide.

Remarques

Dans Internet Explorer 4.0 et versions ultérieures, InternetCanonicalizeUrl fonctionne toujours comme si l’indicateur ICU_BROWSER_MODE est 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 toujours encode 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 les 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 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 de 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 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 est 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.

Remarque 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).

Note

L’en-tête wininet.h définit InternetCanonicalizeUrl comme 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 [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	wininet.h
bibliothèque	Wininet.lib
DLL	Wininet.dll

Voir aussi

gestion des localisateurs de ressources uniformes

fonctions WinINet

Partager via