UrlEscapeA, fonction (shlwapi.h)
Convertit des caractères ou des paires de substitution dans une URL qui peuvent être modifiées pendant le transport sur Internet (« caractères non sécurisés ») en séquences d’échappement correspondantes. Les paires de substitution sont des caractères compris entre U+10000 et U+10FFFF (en UTF-32) ou entre DC00 et DFFF (en UTF-16).
Syntaxe
LWSTDAPI UrlEscapeA(
[in] PCSTR pszUrl,
[out] PSTR pszEscaped,
[in, out] DWORD *pcchEscaped,
DWORD dwFlags
);
Paramètres
[in] pszUrl
Type : PCTSTR
Chaîne terminée par null d’une longueur maximale INTERNET_MAX_URL_LENGTH qui contient une URL complète ou partielle, en fonction de la valeur dans dwFlags.
[out] pszEscaped
Type : PTSTR
Mémoire tampon qui reçoit la chaîne convertie, avec les caractères non sécurisés convertis en séquences d’échappement.
[in, out] pcchEscaped
Type : DWORD*
Pointeur vers une valeur DWORD qui, lors de l’entrée, contient le nombre de caractères dans la mémoire tampon pszEscaped . Avant d’appeler UrlEscape, l’application appelante doit définir la valeur référencée par pcchEscaped sur la taille de la mémoire tampon. Lorsque cette fonction retourne correctement, la valeur reçoit le nombre de caractères écrits dans la mémoire tampon, sans inclure le caractère NULL de fin.
Si un code d’erreur E_POINTER est retourné, la mémoire tampon était trop petite pour contenir le résultat et la valeur référencée par pcchEscaped est définie sur le nombre requis de caractères dans la mémoire tampon. Si d’autres erreurs sont retournées, la valeur référencée par pcchEscaped n’est pas définie.
dwFlags
Type : DWORD
Indicateurs qui indiquent quelle partie de l’URL est fournie dans pszURL et quels caractères de cette chaîne doivent être convertis en séquences d’échappement. Les indicateurs suivants sont définis.
URL_DONT_ESCAPE_EXTRA_INFO (0x02000000)
Utilisé uniquement conjointement avec URL_ESCAPE_SPACES_ONLY pour empêcher la conversion de caractères dans la requête (la partie de l’URL qui suit le premier caractère # ou ? rencontré dans la chaîne). Cet indicateur ne doit pas être utilisé seul, ni combiné avec URL_ESCAPE_SEGMENT_ONLY.
URL_BROWSER_MODE
Défini pour être identique à URL_DONT_ESCAPE_EXTRA_INFO.
URL_ESCAPE_SPACES_ONLY (0x04000000)
Convertissez uniquement les caractères d’espace en séquences d’échappement, y compris les caractères d’espace dans la partie requête de l’URL. Les autres caractères non sécurisés ne sont pas convertis en séquences d’échappement. Cet indicateur suppose que pszURL ne contient pas d’URL complète. Il attend uniquement les parties qui suivent la spécification du serveur.
Combinez cet indicateur avec URL_DONT_ESCAPE_EXTRA_INFO pour empêcher la conversion de caractères d’espace dans la partie requête de l’URL.
Cet indicateur ne peut pas être combiné avec URL_ESCAPE_PERCENT ou URL_ESCAPE_SEGMENT_ONLY.
URL_ESCAPE_PERCENT (0x00001000)
Convertissez tout caractère de % trouvé dans la section segment de l’URL (cette section se trouvant entre la spécification du serveur et le premier caractère # ou ? ). Par défaut, le caractère % n’est pas converti en séquence d’échappement. D’autres caractères non sécurisés dans le segment sont également convertis normalement.
La combinaison de cet indicateur avec URL_ESCAPE_SEGMENT_ONLY inclut ces caractères % dans la partie requête de l’URL. Toutefois, comme l’indicateur URL_ESCAPE_SEGMENT_ONLY fait que la chaîne entière est considérée comme le segment, n’importe quel # ou ? les caractères sont également convertis.
Cet indicateur ne peut pas être combiné avec URL_ESCAPE_SPACES_ONLY.
URL_ESCAPE_SEGMENT_ONLY (0x00002000)
Indique que pszURL contient uniquement la section de l’URL qui suit le composant serveur, mais avant la requête. Tous les caractères non sécurisés de la chaîne sont convertis. Si une URL complète est fournie lorsque cet indicateur est défini, tous les caractères non sécurisés dans l’ensemble de la chaîne sont convertis, y compris les caractères # et ? # et ?.
Combinez cet indicateur avec URL_ESCAPE_PERCENT pour inclure ce caractère dans la conversion.
Cet indicateur ne peut pas être combiné avec URL_ESCAPE_SPACES_ONLY ou URL_DONT_ESCAPE_EXTRA_INFO.
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.
URL_ESCAPE_ASCII_URI_COMPONENT (0x00080000)
Windows 8 et versions ultérieures. Encodez en pourcentage tous les caractères ASCII en dehors du jeu non réservé à partir de l’URI RFC 3986 (a-zA-Z0-9-.~_).
Valeur retournée
Type : HRESULT
Retourne S_OK en cas de réussite. Si la mémoire tampon pcchEscaped était trop petite pour contenir le résultat, E_POINTER est retourné et la valeur pointée par pcchEscaped est définie sur la taille de mémoire tampon requise. Sinon, une valeur d’erreur standard est retournée.
Remarques
Pour les besoins de ce document, une URL classique est divisée en trois sections : le serveur, le segment et la requête. Par exemple :
http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment
La partie serveur est « http://microsoft.com/". La barre oblique de fin est considérée comme faisant partie de la partie serveur.
La partie segment fait partie du chemin d’accès trouvé après la partie serveur, mais avant le premier # ou ? caractère, dans ce cas simplement « test.asp ».
La partie requête est le reste du chemin d’accès du premier # ou ? caractère (inclus) jusqu’à la fin. Dans l’exemple, il s’agit de « ?url=/example/abc.asp ?frame=true#fragment ».
Les caractères non sécurisés sont ceux qui peuvent être modifiés pendant le transport sur Internet. Cette fonction convertit les caractères non sécurisés en séquences d’échappement équivalentes « %xy ». Le tableau suivant présente les caractères non sécurisés et leurs séquences d’échappement.
| Caractère | Séquence d'échappement |
|---|---|
| ^ | %5E |
| & | %26 |
| ` | %60 |
| { | %7B |
| } | %7D |
| | | %7C |
| ] | %5D |
| [ | %5B |
| " | %22 |
| < | %3C |
| > | %3E |
| \ | %5C |
L’utilisation de l’indicateur URL_ESCAPE_SEGMENT_ONLY provoque également la conversion de # (%23), ? (%3F) et / (%2F) caractères.
Par défaut, UrlEscape ignore tout texte suivant un # ou ? . L’indicateur URL_ESCAPE_SEGMENT_ONLY remplace ce comportement en définissant la chaîne entière comme segment. L’indicateur URL_ESCAPE_SPACES_ONLY remplace ce comportement, mais uniquement pour les caractères d’espace.
Exemples
Les exemples suivants montrent l’effet des différents indicateurs sur une URL. L’exemple d’URL n’est pas valide, mais il est exagéré à des fins de démonstration.
// The full original URL
http://microsoft.com/test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SPACES_ONLY
// Only space characters are escaped. Other unsafe characters are ignored.
// Note: This flag expects the server portion of the URL to be omitted.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%e<s%20t.asp?url=/{ex%%20ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SPACES_ONLY | URL_DONT_ESCAPE_EXTRA_INFO
// Spaces in the segment are converted into their escape sequences, but
// spaces in the query are not.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%e<s%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_PERCENT
// Here only the segment and query are supplied and the server component is
// omitted, although that is not required. Only the segment is considered.
// All unsafe characters plus the % character are converted in the segment.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%25e%3Cs%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SEGMENT_ONLY
// Note: This flag expects only the segment, omitting the server and query
// components.
// The / character is escaped as well as the usual unsafe characters.
Original = test/t%e<s t.asp
Result = test%2Ft%e%3Cs%20t.asp
Notes
L’en-tête shlwapi.h définit UrlEscape 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, 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) |