Freigeben über


UrlEscapeA-Funktion (shlwapi.h)

Wandelt Zeichen oder Ersatzpaare in einer URL um, die während des Transports im Internet ("unsichere" Zeichen) in die entsprechenden Escapesequenzen geändert werden können. Ersatzpaare sind Zeichen zwischen U+10000 und U+10FFFF (in UTF-32) oder zwischen DC00 und DFFF (in UTF-16).

Syntax

LWSTDAPI UrlEscapeA(
  [in]      PCSTR pszUrl,
  [out]     PSTR  pszEscaped,
  [in, out] DWORD *pcchEscaped,
            DWORD dwFlags
);

Parameter

[in] pszUrl

Typ: PCTSTR-

Eine mit Null beendete Zeichenfolge mit maximaler Länge INTERNET_MAX_URL_LENGTH, die eine vollständige oder teilweise 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 wurden.

[in, out] pcchEscaped

Typ: DWORD*-

Ein Zeiger auf einen DWORD- Wert, der beim Eintrag die Anzahl der Zeichen im pszEscaped- Puffer enthält. Vor dem Aufrufen UrlEscape-muss die aufrufende Anwendung den Wert festlegen, auf den pcchEscaped auf die Größe des Puffers verweist. Wenn diese Funktion erfolgreich zurückgegeben wird, empfängt der Wert die Anzahl der Zeichen, die in den Puffer geschrieben wurden, nicht einschließlich des endenden NULL- Zeichens.

Wenn ein E_POINTER Fehlercode zurückgegeben wird, war der Puffer zu klein, um das Ergebnis zu speichern, und der Wert, auf den pcchEscaped verweist, wird auf die erforderliche Anzahl von Zeichen im Puffer festgelegt. Wenn andere Fehler zurückgegeben werden, ist der Wert, auf den pcchEscaped verweist, nicht definiert.

dwFlags

Typ: 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 werden 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 #- oder ? Zeichen in der Zeichenfolge). Diese Kennzeichnung sollte nicht allein verwendet werden oder mit URL_ESCAPE_SEGMENT_ONLYkombiniert werden.

URL_BROWSER_MODE

Definiert, um mit URL_DONT_ESCAPE_EXTRA_INFOidentisch zu sein.

URL_ESCAPE_SPACES_ONLY (0x04000000)

Konvertieren Sie nur Leerzeichen in ihre Escapesequenzen, einschließlich dieser Leerzeichen im Abfragebereich 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 erwartet nur die Teile, die der Serverspezifikation folgen.

Kombinieren Sie dieses Flag mit URL_DONT_ESCAPE_EXTRA_INFO, um die Konvertierung von Leerzeichen im Abfragebereich der URL zu verhindern.

Dieses Kennzeichen kann nicht mit URL_ESCAPE_PERCENT oder URL_ESCAPE_SEGMENT_ONLYkombiniert werden.

URL_ESCAPE_PERCENT (0x00001000)

Konvertieren Sie ein beliebiges % Zeichen im Abschnitt "Segment" der URL (dieser Abschnitt fällt zwischen der Serverspezifikation und dem ersten # oder ? Zeichen). Standardmäßig wird das % Zeichen nicht in die Escapesequenz konvertiert. Andere unsichere Zeichen im Segment werden ebenfalls normal konvertiert.

Das Kombinieren dieses Flags mit URL_ESCAPE_SEGMENT_ONLY enthält diese % Zeichen im Abfragebereich der URL. Da die URL_ESCAPE_SEGMENT_ONLY-Kennzeichnung jedoch bewirkt, dass die gesamte Zeichenfolge als Segment, ein beliebiges # oder ? Zeichen werden ebenfalls konvertiert.

Dieses Kennzeichen kann nicht mit URL_ESCAPE_SPACES_ONLYkombiniert werden.

URL_ESCAPE_SEGMENT_ONLY (0x00002000)

Gibt an, dass pszURL- nur diesen Abschnitt der URL enthält, der auf die Serverkomponente folgt, aber vor der Abfrage. Alle unsicheren Zeichen in der Zeichenfolge werden konvertiert. Wenn beim Festlegen dieses Flags eine vollständige URL angegeben wird, werden alle unsicheren Zeichen in der gesamten Zeichenfolge konvertiert, einschließlich # und ? Zeichen.

Kombinieren Sie dieses Kennzeichen mit URL_ESCAPE_PERCENT, um dieses Zeichen in die Konvertierung einzuschließen.

Dieses Kennzeichen kann nicht mit URL_ESCAPE_SPACES_ONLY oder URL_DONT_ESCAPE_EXTRA_INFOkombiniert werden.

URL_ESCAPE_AS_UTF8 (0x00040000)

Windows 7 und höher. Prozentcodierung aller Nicht-ASCII-Zeichen als UTF-8-Entsprechungen.

URL_ESCAPE_ASCII_URI_COMPONENT (0x00080000)

Windows 8 und höher. Prozentcodierung aller ASCII-Zeichen außerhalb des nicht reservierten URI RFC 3986 (a-zA-Z0-9-.~_).

Rückgabewert

Typ: HRESULT-

Gibt S_OK zurück, wenn dies erfolgreich ist. 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.

Bemerkungen

Für die Zwecke dieses Dokuments ist eine typische URL in drei Abschnitte unterteilt: der Server, das Segment und die Abfrage. Zum Beispiel:

http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment

Der Serverteil ist "http://microsoft.com/". Der nachfolgende Schrägstrich wird als Teil des Serverteils betrachtet.

Der Segmentteil ist ein Teil des Pfads, der nach dem Serverteil gefunden wird, aber vor dem ersten # oder ? in diesem Fall einfach "test.asp".

Der Abfrageteil ist der Rest des Pfads aus der ersten # oder ? Zeichen (einschließlich) bis zum Ende. Im Beispiel ist es "?url=/example/abc.asp?frame=true#fragment".

Unsichere Zeichen sind die Zeichen, die während des Transports im Internet möglicherweise geändert werden. Diese Funktion wandelt unsichere Zeichen in die entsprechenden Escapesequenzen "%xy" um. Die folgende Tabelle enthält unsichere Zeichen und deren Escapesequenzen.

Zeichen Escape-Sequenz
^ %5E
& %26
` %60
{ %7B
} %7D
| %7C
] %5D
[ %5B
" %22
< %3C
> %3E
\ %5C
 

Die Verwendung des URL_ESCAPE_SEGMENT_ONLY Flags verursacht auch die Konvertierung der # (%23), ? (%3F) und / (%2F) Zeichen.

Standardmäßig ignoriert UrlEscape Text nach einem # oder ? Zeichen. Das URL_ESCAPE_SEGMENT_ONLY-Flag setzt dieses Verhalten außer Kraft, indem die gesamte Zeichenfolge als Segment verwendet wird. Das URL_ESCAPE_SPACES_ONLY Flag setzt dieses Verhalten außer Kraft, jedoch nur für Leerzeichen.

Beispiele

Die folgenden Beispiele zeigen die Auswirkung der verschiedenen Flags auf eine URL. Die Beispiel-URL ist ungültig, wird jedoch 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

Anmerkung

Der Header "shlwapi.h" 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
mindestens unterstützte Client- Windows 2000 Professional, Windows XP [nur Desktop-Apps]
mindestens unterstützte Server- Windows 2000 Server [nur Desktop-Apps]
Zielplattform- Fenster
Header- shlwapi.h
Library Shlwapi.lib
DLL- Shlwapi.dll (Version 5.0 oder höher)

Siehe auch

Behandeln von Uniform Resource Locators