UrlEscapeA, fonction (shlwapi.h)
Convertit des caractères ou des paires de substitution dans une URL qui peut être modifiée pendant le transport sur Internet (« caractères non sécurisés ») dans leurs 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 de longueur maximale INTERNET_MAX_URL_LENGTH qui contient une URL complète ou partielle, selon les besoins 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 la fin caractère NULL.
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 (partie de l’URL suivant le premier # ou ? caractère rencontré dans la chaîne). Cet indicateur ne doit pas être utilisé seul, ni combiné à URL_ESCAPE_SEGMENT_ONLY.
URL_BROWSER_MODE
Défini comme étant identique à URL_DONT_ESCAPE_EXTRA_INFO.
URL_ESCAPE_SPACES_ONLY (0x04000000)
Convertissez uniquement des caractères d’espace en séquences d’échappement, y compris ces espaces 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. Elle 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 un caractère % trouvé dans la section segment de l’URL (cette section tombant entre la spécification du serveur et le premier # ou ? caractère). 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 de URL_ESCAPE_SEGMENT_ONLY entraîne la prise en compte de la chaîne entière comme 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 cette section de l’URL qui suit le composant serveur, mais qui précède la requête. Tous les caractères non sécurisés dans 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 de la chaîne entière sont convertis, y compris # et ? caractères.
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. Encoder 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 de retour
Type : HRESULT
Retourne S_OK en cas de réussite. Si la mémoire tampon pcchEscaped
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 de requête est le reste du chemin d’accès du premier # ou ? caractère (inclusif) à 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 leurs séquences d’échappement «%xy» équivalentes. Le tableau suivant présente des caractères non sécurisés et leurs séquences d’échappement.
| Personnage | 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 du # (%23), ? (%3F), et / (%2F) caractères.
Par défaut, UrlEscape ignore tout texte suivant un # ou ? personnage. L’indicateur URL_ESCAPE_SEGMENT_ONLY remplace ce comportement en ce qui concerne la chaîne entière en tant que 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 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
Note
L’en-tête shlwapi.h définit UrlEscape 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, 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) |