Fonction InternetCanonicalizeUrlA (wininet.h)
Canonisation d’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 à canonicaliser.
[out] lpszBuffer
Pointeur vers la mémoire tampon qui reçoit l’URL canonisée 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 effectivement 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, ce qui inclut le caractère null de fin.
[in] dwFlags
Contrôle la canonicalisation. Si aucun indicateur n’est spécifié, la fonction convertit tous les caractères et métadonnées non sécurisés (tels que .,\ .., et ...) en séquences d’échappement. Ce paramètre peut prendre les valeurs suivantes.
| Valeur | Signification |
|---|---|
|
N’encode pas ou ne décode pas 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 les espaces blancs de fin sont supprimés. |
|
Convertit toutes les séquences %XX en caractères, y compris les séquences d’échappement, avant l’analyse de l’URL. |
|
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. |
|
Encode uniquement les espaces. |
|
Ne convertit pas les caractères non sécurisés en séquences d’échappement. |
|
Ne supprime pas les séquences de métadonnées (telles que « » et « . . ») de l’URL. |
Valeur retournée
Retourne LA valeur TRUE si elle réussit 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 |
|---|---|
|
L’URL n’a pas pu être canonisée. |
|
L’URL canonisée 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. |
|
Le format de l’URL n’est pas valide. |
|
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 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 d’une URL ont été convertis en séquences d’échappement, l’utilisation d’InternetCanonicalizeUrl 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înerait 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.
Notes
L’en-tête wininet.h définit InternetCanonicalizeUrl 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 [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 |