UrlEscapeW-Funktion (shlwapi.h)
Konvertiert Zeichen oder Ersatzzeichenpaare in einer URL, die während des Transports über das Internet geändert werden können ("unsichere" Zeichen) in die entsprechenden Escapesequenzen. Ersatzpaare sind Zeichen zwischen U+10000 und U+10FFFF (in UTF-32) oder zwischen DC00 und DFFF (in UTF-16).
Syntax
LWSTDAPI UrlEscapeW(
[in] PCWSTR pszUrl,
[out] PWSTR pszEscaped,
[in, out] DWORD *pcchEscaped,
DWORD dwFlags
);
Parameter
[in] pszUrl
Typ: PCTSTR
Eine null-endende Zeichenfolge mit maximaler Länge INTERNET_MAX_URL_LENGTH , die eine vollständige oder partielle URL enthält, je nach Wert in dwFlags.
[out] pszEscaped
Typ: PTSTR
Der Puffer, der die konvertierte Zeichenfolge empfängt, wobei die unsicheren Zeichen in ihre Escapesequenzen konvertiert werden.
[in, out] pcchEscaped
Typ: DWORD*
Ein Zeiger auf einen DWORD-Wert , der bei einem Eintrag die Anzahl der Zeichen im puffer pszEscaped enthält. Vor dem Aufrufen von UrlEscape muss die aufrufende Anwendung den Wert, auf den von pcchEscaped verwiesen wird, auf die Größe des Puffers festlegen. Wenn diese Funktion erfolgreich zurückgibt, empfängt der Wert die Anzahl der Zeichen, die in den Puffer geschrieben wurden, ohne das abschließende NULL-Zeichen .
Wenn ein E_POINTER Fehlercode zurückgegeben wird, war der Puffer zu klein, um das Ergebnis zu speichern, und der Wert, auf den von pcchEscaped verwiesen wird, wird auf die erforderliche Anzahl von Zeichen im Puffer festgelegt. Wenn andere Fehler zurückgegeben werden, ist der Wert, auf den von pcchEscaped verwiesen wird, undefiniert.
dwFlags
Art: DWORD
Die Flags, die angeben, welcher Teil der URL in pszURL bereitgestellt wird und welche Zeichen in dieser Zeichenfolge in ihre Escapesequenzen konvertiert werden sollen. Die folgenden Flags sind definiert.
URL_DONT_ESCAPE_EXTRA_INFO (0x02000000)
Wird nur in Verbindung mit URL_ESCAPE_SPACES_ONLY verwendet, um die Konvertierung von Zeichen in der Abfrage zu verhindern (der Teil der URL nach dem ersten Zeichen #oder ? in der Zeichenfolge). Dieses Flag sollte nicht allein verwendet oder mit URL_ESCAPE_SEGMENT_ONLY kombiniert werden.
URL_BROWSER_MODE
Definiert, um mit URL_DONT_ESCAPE_EXTRA_INFO identisch zu sein.
URL_ESCAPE_SPACES_ONLY (0x04000000)
Konvertieren Sie nur Leerzeichen in ihre Escapesequenzen, einschließlich der Leerzeichen im Abfrageteil der URL. Andere unsichere Zeichen werden nicht in ihre Escapesequenzen konvertiert. Bei diesem Flag wird davon ausgegangen, dass pszURL keine vollständige URL enthält. Es wird nur die Teile erwartet, die der Serverspezifikation entsprechen.
Kombinieren Sie dieses Flag mit URL_DONT_ESCAPE_EXTRA_INFO , um die Konvertierung von Leerzeichen im Abfrageteil der URL zu verhindern.
Dieses Flag kann nicht mit URL_ESCAPE_PERCENT oder URL_ESCAPE_SEGMENT_ONLY kombiniert werden.
URL_ESCAPE_PERCENT (0x00001000)
Konvertieren Sie ein beliebiges %-Zeichen im Segmentabschnitt der URL (dieser Abschnitt, der zwischen der Serverspezifikation und dem ersten #- oder ? -Zeichen liegt). Standardmäßig wird das Zeichen %nicht in seine Escapesequenz konvertiert. Andere unsichere Zeichen im Segment werden ebenfalls normal konvertiert.
Wenn Sie dieses Flag mit URL_ESCAPE_SEGMENT_ONLY kombinieren, werden diese %-Zeichen im Abfrageteil der URL eingeschlossen. Da das URL_ESCAPE_SEGMENT_ONLY-Flag jedoch bewirkt, dass die gesamte Zeichenfolge als Segment betrachtet wird, kann ein # oder ein ? Zeichen werden ebenfalls konvertiert.
Dieses Flag kann nicht mit URL_ESCAPE_SPACES_ONLY kombiniert werden.
URL_ESCAPE_SEGMENT_ONLY (0x00002000)
Gibt an, dass pszURL nur den Abschnitt der URL enthält, der der Serverkomponente folgt, aber der Abfrage vorangeht. Alle unsicheren Zeichen in der Zeichenfolge werden konvertiert Wenn eine vollständige URL angegeben wird, wenn dieses Flag festgelegt ist, werden alle unsicheren Zeichen in der gesamten Zeichenfolge konvertiert, einschließlich der #- und ?- Zeichen.
Kombinieren Sie dieses Flag mit URL_ESCAPE_PERCENT , um dieses Zeichen in die Konvertierung einzuschließen.
Dieses Flag kann nicht mit URL_ESCAPE_SPACES_ONLY oder URL_DONT_ESCAPE_EXTRA_INFO kombiniert werden.
URL_ESCAPE_AS_UTF8 (0x00040000)
Windows 7 und höher. Alle Nicht-ASCII-Zeichen als UTF-8-Entsprechungen werden prozentual codiert.
URL_ESCAPE_ASCII_URI_COMPONENT (0x00080000)
Windows 8 und höher. Prozentcodierung aller ASCII-Zeichen außerhalb des nicht reservierten Satzes aus URI RFC 3986 (a-zA-Z0-9-.~_).
Rückgabewert
Typ: HRESULT
Gibt bei erfolgreicher Ausführung S_OK zurück. Wenn der pcchEscaped-Puffer zu klein war, um das Ergebnis zu enthalten, wird E_POINTER zurückgegeben, und der Wert, auf den pcchEscaped verweist, wird auf die erforderliche Puffergröße festgelegt. Andernfalls wird ein Standardfehlerwert zurückgegeben.
Hinweise
Für die Zwecke dieses Dokuments wird eine typische URL in drei Abschnitte unterteilt: den Server, das Segment und die Abfrage. Beispiel:
http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment
Der Serverteil ist "http://microsoft.com/". Der nachgestellte Schrägstrich wird als Teil des Serverteils betrachtet.
Der Segmentteil ist ein beliebiger Teil des Pfads, der dem Serverteil folgt, aber vor dem ersten # oder ? Zeichen, in diesem Fall einfach "test.asp".
Der Abfrageteil ist der Rest des Pfads vom ersten # oder ? Zeichen (inklusive) bis zum Ende. Im Beispiel lautet dies "?url=/example/abc.asp?frame=true#fragment".
Unsichere Zeichen sind Zeichen, die während des Transports über das Internet geändert werden können. Diese Funktion konvertiert unsichere Zeichen in die entsprechenden "%xy"-Escapesequenzen. Die folgende Tabelle enthält unsichere Zeichen und deren Escapesequenzen.
| Zeichen | Escapesequenz |
|---|---|
| ^ | %5E |
| & | %26 |
| ` | %60 |
| { | %7B |
| } | %7D |
| | | %7C |
| ] | %5D |
| [ | %5B |
| " | %22 |
| < | %3C |
| > | %3E |
| \ | %5C |
Die Verwendung des URL_ESCAPE_SEGMENT_ONLY Flags verursacht auch die Konvertierung von # (%23), ? (%3F) und / (%2F) Zeichen.
Standardmäßig ignoriert UrlEscape jeden Text, der einem # oder ? befinden. Das URL_ESCAPE_SEGMENT_ONLY-Flag überschreibt dieses Verhalten, indem die gesamte Zeichenfolge als Segment verwendet wird. Das URL_ESCAPE_SPACES_ONLY-Flag überschreibt dieses Verhalten, jedoch nur für Leerzeichen.
Beispiele
Die folgenden Beispiele zeigen die Auswirkungen der verschiedenen Flags auf eine URL. Die Beispiel-URL ist ungültig, aber zu Demonstrationszwecken übertrieben.
// 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
Hinweis
Der shlwapi.h-Header definiert UrlEscape als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional, Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | shlwapi.h |
| Bibliothek | Shlwapi.lib |
| DLL | Shlwapi.dll (Version 5.0 oder höher) |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für