UrlCanonicalizeW-Funktion (shlwapi.h)

  • Artikel

Konvertiert eine URL-Zeichenfolge in ein kanonisches Format.

Syntax

LWSTDAPI UrlCanonicalizeW(
  [in]      PCWSTR pszUrl,
  [out]     PWSTR  pszCanonicalized,
  [in, out] DWORD  *pcchCanonicalized,
            DWORD  dwFlags
);

Parameter

[in] pszUrl

Typ: PCTSTR

Ein Zeiger auf eine null-endende Zeichenfolge mit maximaler Länge INTERNET_MAX_URL_LENGTH, die eine URL-Zeichenfolge enthält. Wenn die Zeichenfolge nicht auf eine Datei verweist, muss diese ein gültiges Schema wie „http://“ enthalten.

[out] pszCanonicalized

Typ: PTSTR

Ein Zeiger auf einen Puffer, der die konvertierte URL als null-beendete Zeichenfolge empfängt, wenn diese Funktion erfolgreich zurückgibt.

[in, out] pcchCanonicalized

Typ: DWORD*

Ein Zeiger auf einen Wert, der bei der Eingabe auf die Anzahl der Zeichen im pszCanonicalized-Puffer festgelegt wird.

dwFlags

Art: DWORD

Die Flags, die angeben, wie die URL in kanonische Form konvertiert wird. Die folgenden Flags können kombiniert werden.

URL_UNESCAPE (0x10000000)

Heben Sie die Escapesequenzen, die die URLs enthalten, mit zwei Ausnahmen auf. Die Escapezeichen für die Escapesequenzen für ? und # wurden nicht entfernt. Wenn auch eines der URL_ESCAPE_XXX-Flags festgelegt ist, werden die beiden URLs zunächst nicht mit Escapezeichen versehen, dann kombiniert und dann mit Escapezeichen versehen.

URL_ESCAPE_UNSAFE (0x20000000)

Ersetzt unsichere Zeichen durch entsprechende Escapesequenzen. Unsichere Zeichen sind Die Zeichen, die während des Transports über das Internet geändert werden können, und enthalten die Zeichen (<, >, ", #, {, }, |, , ^, [, ] und '). Dieses Flag gilt für alle URLs, einschließlich opaken URLs.

URL_PLUGGABLE_PROTOCOL (0x40000000)

Kombinieren Sie URLs mit clientdefiniert austauschbaren Protokollen gemäß der W3C-Spezifikation. Dieses Flag gilt nicht für Standardprotokolle wie FTP, HTTP und Gopher. Wenn dieses Flag festgelegt ist, vereinfacht UrlCombine urLs nicht, sodass es nicht erforderlich ist, auch URL_DONT_SIMPLIFY festzulegen.

URL_ESCAPE_SPACES_ONLY (0x04000000)

Ersetzt nur Leerzeichen durch Escapesequenzen. Dieses Flag hat Vorrang vor URL_ESCAPE_UNSAFE, gilt jedoch nicht für undurchsichtige URLs.

URL_DONT_SIMPLIFY (0x08000000)

Behandelt „/./“ und „/../“ in einer URL-Zeichenfolge als Literalzeichen und nicht als Kurzform für die Navigation. Weitere Informationen finden Sie in den Anmerkungen.

URL_NO_META (0x08000000)

Definiert, um mit URL_DONT_SIMPLIFY identisch zu sein.

URL_ESCAPE_PERCENT (0x00001000)

Konvertiert „%“ immer in die entsprechende Escapesequenz.

URL_ESCAPE_AS_UTF8 (0x00040000)

Windows 7 und höher. Alle Nicht-ASCII-Zeichen als UTF-8-Entsprechungen werden prozentual codiert.

Rückgabewert

Typ: HRESULT

Wenn diese Funktion erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Diese Funktion führt Aufgaben wie das Ersetzen unsicherer Zeichen durch ihre Escapesequenzen und das Reduzieren von Sequenzen wie "....." aus.

Wenn eine URL-Zeichenfolge "/.. enthält. /" oder "/./", UrlCanonicalize behandelt die Zeichen als Angabe der Navigation in der URL-Hierarchie. Die Funktion vereinfacht die URLs, bevor sie kombiniert werden. Für instance "/hello/cruel/.. /world" wird in "/hello/world" vereinfacht. Ausnahmen von diesem Standardverhalten treten in folgenden Fällen auf:

  • Wenn das URL_DONT_SIMPLIFY-Flag in dwFlags festgelegt ist, vereinfacht die Funktion urLs nicht. In diesem Fall "/hello/cruel/.. /world" bleibt unverändert.
  • Wenn "/.. /" oder "/./" ist das erste Segment im Pfad (z. B. "http://domain/../path1/path2/file.htm"), UrlCanonicalize gibt den Pfad genau so aus, wie er eingegeben wurde.

Hinweis

Der shlwapi.h-Header definiert UrlCanonicalize 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

Behandeln von Uniform Resource Locators