InternetCanonicalizeUrlA-Funktion (wininet.h)

Artikel
08/27/2023

Kanonisiert eine URL, die das Konvertieren unsicherer Zeichen und Leerzeichen in Escapesequenzen umfasst.

Syntax

BOOL InternetCanonicalizeUrlA(
  [in]      LPCSTR  lpszUrl,
  [out]     LPSTR   lpszBuffer,
  [in, out] LPDWORD lpdwBufferLength,
  [in]      DWORD   dwFlags
);

Parameter

[in] lpszUrl

Ein Zeiger auf die Zeichenfolge, die die zu kanonisierende URL enthält.

[out] lpszBuffer

Ein Zeiger auf den Puffer, der die resultierende kanonisierte URL empfängt.

[in, out] lpdwBufferLength

Ein Zeiger auf eine Variable, die die Größe des lpszBuffer-Puffers in Zeichen enthält. Wenn die Funktion erfolgreich ist, empfängt dieser Parameter die Anzahl der Zeichen, die tatsächlich in den lpszBuffer-Puffer kopiert wurden, wobei das beendende NULL-Zeichen nicht enthalten ist. Wenn die Funktion fehlschlägt, empfängt dieser Parameter die erforderliche Größe des Puffers in Zeichen, die das beendende NULL-Zeichen enthält.

[in] dwFlags

Steuert die Kanonisierung. Wenn keine Flags angegeben sind, konvertiert die Funktion alle unsicheren Zeichen und Metasequenzen (z. B. .,\ .., und ...) in Escapesequenzen. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
ICU_BROWSER_MODE	Codiert oder decodiert keine Zeichen nach "#" oder "?", und entfernt nach "?" nicht den nachfolgenden Leerraum. Wenn dieser Wert nicht angegeben wird, wird die gesamte URL codiert, und der nachfolgende Leerraum wird entfernt.
ICU_DECODE	Konvertiert alle %XX-Sequenzen in Zeichen, einschließlich Escapesequenzen, bevor die URL analysiert wird.
ICU_ENCODE_PERCENT	Codiert alle gefundenen Prozentzeichen. Standardmäßig sind Prozentzeichen nicht codiert. Dieser Wert ist in Microsoft Internet Explorer 5 und höher verfügbar.
ICU_ENCODE_SPACES_ONLY	Codiert nur Leerzeichen.
ICU_NO_ENCODE	Konvertiert keine unsicheren Zeichen in Escapesequenzen.
ICU_NO_META	Entfernt keine Metasequenzen (z. B. "." und "..") aus der URL.

Rückgabewert

Gibt TRUE zurück, wenn der Vorgang erfolgreich war, oder andernfalls FALSE . Um erweiterte Fehlerinformationen zu erhalten, rufen Sie die GetLastError-Funktion auf. Zu den möglichen Fehlern zählen die folgenden.

Rückgabecode	Beschreibung
ERROR_BAD_PATHNAME	Die URL konnte nicht kanonisiert werden.
ERROR_INSUFFICIENT_BUFFER	Die kanonisierte URL ist zu groß, um in den bereitgestellten Puffer zu passen. Der lpdwBufferLength-Parameter ist auf die Größe des Puffers in Bytes festgelegt, der für die kanonisierte URL erforderlich ist.
ERROR_INTERNET_INVALID_URL	Das Format der URL ist ungültig.
ERROR_INVALID_PARAMETER	Es gibt einen ungültigen Parameter für Zeichenfolge, Puffer, Puffergröße oder Flags.

Hinweise

In Internet Explorer 4.0 und höher funktioniert InternetCanonicalizeUrl immer so, als ob das ICU_BROWSER_MODE-Flag festgelegt ist. Clientanwendungen, die die gesamte URL kanonisieren müssen, sollten entweder CoInternetParseUrl (mit der Aktion PARSE_CANONICALIZE und dem Flag URL_ESCAPE_UNSAFE) oder UrlCanonicalize verwenden.

InternetCanonicalizeUrl wird immer standardmäßig codiert, auch wenn das ICU_DECODE-Flag angegeben wurde. Verwenden Sie zum Decodieren ohne Erneutes Decodieren ICU_DECODE | ICU_NO_ENCODE. Wenn das ICU_DECODE-Flag ohne ICU_NO_ENCODE verwendet wird, wird die URL vor der Analyse decodiert. unsichere Zeichen werden nach der Analyse erneut codiert. Diese Funktion verarbeitet beliebige Protokollschemas, muss aber dazu Rückschlüsse aus dem unsicheren Zeichensatz ziehen.

Anwendungen, die InternetCanonicalizeUrl bei Verwendung von Internet Explorer 3.0 (oder beim Festlegen des ICU_ENCODE_PERCENT-Flags für Internet Explorer 5 und höher) aufrufen, sollten die Verwendung dieser Funktion auf einer bestimmten URL nachverfolgen. Wenn unsichere Zeichen in einer URL in Escapesequenzen konvertiert wurden, werden die Escapesequenzen durch erneute Verwendung von InternetCanonicalizeUrl auf der URL (ohne Flags) in eine andere Escapesequenz konvertiert. Beispielsweise würde ein Leerzeichen in einer URL in die Escapesequenz %20 konvertiert. Das erneute Aufrufen von InternetCanonicalizeUrl auf der URL würde dazu führen, dass die Escapesequenz %20 in die Escapesequenz %2520 konvertiert wird, da das %-Zeichen ein unsicheres Zeichen ist, das für Escapesequenzen reserviert ist und durch die Funktion durch die Escapesequenz %25 ersetzt wird.

Wie alle anderen Aspekte der WinINet-API kann diese Funktion nicht sicher innerhalb von DllMain oder den Konstruktoren und Destruktoren globaler Objekte aufgerufen werden.

Hinweis WinINet unterstützt keine Serverimplementierungen. Darüber hinaus sollte es nicht von einem Dienst aus verwendet werden. Verwenden Sie für Serverimplementierungen oder Dienste Microsoft Windows HTTP Services (WinHTTP).

Hinweis

Der wininet.h-Header definiert InternetCanonicalizeUrl 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 nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	wininet.h
Bibliothek	Wininet.lib
DLL	Wininet.dll

Weitere Informationen

Behandeln von Uniform Resource Locators

WinINet-Funktionen

Share via