Fonction UrlEscapeW (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 ») 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 UrlEscapeW(
  [in]      PCWSTR pszUrl,
  [out]     PWSTR  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 de caractères requis 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 comme étant 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 ces 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 part du principe que pszURL ne contient pas d’URL complète. Il attend uniquement les parties suivant 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 % de caractère 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. Les autres caractères non sécurisés du 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 cette 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 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 « %xy » équivalentes. Le tableau suivant montre les caractères non sécurisés et leurs séquences d’échappement.

L’utilisation de l’indicateur URL_ESCAPE_SEGMENT_ONLY entraîne également la conversion de # (%23), ? Caractères (%3F) et / (%2F).

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 espaces.

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

Configuration requise

Voir aussi

Gestion des localisateurs de ressources uniformes