IdnToAscii-Funktion (winnls.h)

Artikel
08/27/2023

Konvertiert einen internationalisierten Domänennamen (IDN) oder eine andere internationalisierte Bezeichnung in eine Unicode-Darstellung (Breitzeichen) der ASCII-Zeichenfolge, die den Namen in der Punycode-Übertragungscodierungssyntax darstellt.

Vorsicht Diese Funktion implementiert den Standardalgorithmus RFC 3490: Internationalizing Domain Names in Applications (IDNA) zum Konvertieren eines IDN in Punycode. Der Standard führt zu einigen Sicherheitsproblemen. Ein Problem besteht darin, dass Glyphen, die bestimmte Zeichen aus verschiedenen Skripts darstellen, ähnlich oder sogar identisch aussehen können. Beispielsweise ist in vielen Schriftarten der kyrillische Kleinbuchstaben A ("а") nicht von lateinischem Kleinbuchstaben A ("a") zu unterscheiden. Es gibt keine Möglichkeit, visuell zu sagen, dass "example.com" und "exа mple.com" zwei verschiedene Domänennamen sind, einer mit einem lateinischen Kleinbuchstaben A im Namen, der andere mit einem kyrillischen Kleinbuchstaben A. Weitere Informationen zu IDN-bezogenen Sicherheitsbedenken finden Sie unter Handling Internationalized Domain Names (IDNs).

Syntax

int IdnToAscii(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpUnicodeCharStr,
  [in]            int     cchUnicodeChar,
  [out, optional] LPWSTR  lpASCIICharStr,
  [in]            int     cchASCIIChar
);

Parameter

[in] dwFlags

Flags, die Konvertierungsoptionen angeben. In der folgenden Tabelle sind die möglichen Werte aufgeführt.

Wert	Bedeutung
IDN_ALLOW_UNASSIGNED	Hinweis Eine Anwendung kann diesen Wert festlegen, wenn sie nur eine Abfragezeichenfolge für die normale Suche verwendet, wie bei einem Vergleichsvorgang. Die Anwendung sollte diesen Wert jedoch nicht für eine gespeicherte Zeichenfolge festlegen, bei der es sich um eine Zeichenfolge handelt, die für den Speicher vorbereitet wird. Zulassen, dass nicht zugewiesene Codepunkte in die Eingabezeichenfolge eingeschlossen werden. Die Standardeinstellung besteht darin, nicht zugewiesene Codepunkte nicht zuzulassen und mit einem erweiterten Fehlercode von ERROR_INVALID_NAME fehlschlagen. Dieses Flag ermöglicht es der Funktion, Zeichen zu verarbeiten, die in IDNs derzeit nicht zulässig sind, aber in späteren Versionen des IDNA-Standards möglicherweise zulässig sind. Wenn Ihre Anwendung nicht zugewiesene Codepunkte als Punycode codiert, sollten die resultierenden Domänennamen unzulässig sein. Die Sicherheit kann gefährdet werden, wenn eine höhere Version von IDNA diese Namen legal macht oder wenn eine Anwendung die unzulässigen Zeichen herausfiltert, um einen legalen Domänennamen zu erstellen. Weitere Informationen finden Sie unter Handling Internationalized Domain Names (IDNs).
IDN_USE_STD3_ASCII_RULES	Filtert ASCII-Zeichen heraus, die in STD3-Namen nicht zulässig sind. Die einzigen ascii-Zeichen, die in der Unicode-Eingabezeichenfolge zulässig sind, sind Buchstaben, Ziffern und der Bindestrich-Minus. Die Zeichenfolge kann nicht mit dem Bindestrich-Minus beginnen oder enden. Die Funktion schlägt fehl, wenn die Unicode-Eingabezeichenfolge ASCII-Zeichen wie "[", "]" oder "/" enthält, die in Domänennamen nicht vorkommen können. Hinweis Einige lokale Netzwerke können einige dieser Zeichen in Computernamen zulassen. Die Funktion schlägt fehl, wenn die Unicode-Eingabezeichenfolge Steuerzeichen (U+0001 bis U+0020) oder das Löschzeichen (U+007F) enthält. In beiden Fällen hat dieses Flag keine Auswirkungen auf die Nicht-ASCII-Zeichen, die in der Unicode-Zeichenfolge zulässig sind.
IDN_EMAIL_ADDRESS	Ab Windows 8: Aktivieren Sie das algorithmische EAI-Fallback für die lokalen Teile von E-Mail-Adressen (z<. B. local>@microsoft.com). Standardmäßig schlägt diese Funktion fehl, wenn eine E-Mail-Adresse über eine ungültige Adresse oder Syntax verfügt. Eine Anwendung kann dieses Flag festlegen, damit Email Address Internationalization (EAI) nach Möglichkeit eine auffindbare Fallbackadresse zurückgibt. Weitere Informationen finden Sie in der IETF Email Address Internationalization Charter (eai).
IDN_RAW_PUNYCODE	Ab Windows 8: Deaktivieren Sie die Überprüfung und Zuordnung von Punycode.

[in] lpUnicodeCharStr

Zeiger auf eine Unicode-Zeichenfolge, die einen IDN oder eine andere internationalisierte Bezeichnung darstellt.

[in] cchUnicodeChar

Anzahl der Zeichen in der Unicode-Eingabezeichenfolge, die durch lpUnicodeCharStr angegeben wird.

[out, optional] lpASCIICharStr

Zeiger auf einen Puffer, der eine Unicode-Zeichenfolge empfängt, die nur aus Zeichen im ASCII-Zeichensatz besteht. Bei Rückgabe dieser Funktion enthält der Puffer das ASCII-Zeichenfolgenäquivalent der Zeichenfolge, die in lpUnicodeCharStr unter Punycode bereitgestellt wird. Alternativ kann die Funktion NULL für diesen Parameter abrufen, wenn cchASCIIChar auf 0 festgelegt ist. In diesem Fall gibt die Funktion die für diesen Puffer erforderliche Größe zurück.

[in] cchASCIIChar

Größe des Puffers, der durch lpASCIICharStr angegeben wird. Die Anwendung kann den Parameter auf 0 festlegen, um NULL in lpASCIICharStr abzurufen.

Rückgabewert

Gibt bei erfolgreicher Ausführung die Anzahl der in lpASCIICharStr abgerufenen Zeichen zurück. Die abgerufene Zeichenfolge ist nur dann NULL-endend, wenn die Eingabe-Unicode-Zeichenfolge null-terminated ist.

Wenn die Funktion erfolgreich ist und der Wert von cchASCIIChar 0 ist, gibt die Funktion die erforderliche Größe in Zeichen zurück, einschließlich eines abschließenden NULL-Zeichens, wenn es Teil des Eingabepuffers war.

Die Funktion gibt 0 zurück, wenn sie nicht erfolgreich ist. Um erweiterte Fehlerinformationen zu erhalten, kann die Anwendung GetLastError aufrufen, wodurch einer der folgenden Fehlercodes zurückgegeben werden kann:

ERROR_INSUFFICIENT_BUFFER. Eine angegebene Puffergröße war nicht groß genug, oder sie wurde fälschlicherweise auf NULL festgelegt.
ERROR_INVALID_FLAGS. Die für Flags angegebenen Werte waren ungültig.
ERROR_INVALID_NAME. Für die Funktion wurde ein ungültiger Name angegeben. Beachten Sie, dass dieser Fehlercode alle Syntaxfehler abfängt.
ERROR_INVALID_PARAMETER. Jeder der Parameterwerte war ungültig.
ERROR_NO_UNICODE_TRANSLATION. In einer Zeichenfolge wurde ein ungültiger Unicode-Code gefunden.

Hinweise

Die Funktion beendet eine Ausgabezeichenfolge nicht null, wenn die Länge der Eingabezeichenfolge explizit ohne ein abschließendes NULL-Zeichen angegeben wird. Um eine Ausgabezeichenfolge für diese Funktion null zu beenden, muss die Anwendung -1 für den cchUnicodeChar-Parameter angeben oder explizit das abschließende NULL-Zeichen für die Eingabezeichenfolge zählen.

Beachten Sie, dass die Funktion immer fehlschlägt, wenn die Eingabezeichenfolge Steuerzeichen (U+0001 bis U+0020) oder das Löschzeichen (U+007F) enthält. Da das Zeichen U+0000 nur als beendendes NULL-Zeichen angezeigt werden kann, schlägt die Funktion immer fehl, wenn U+0000 an einer anderen Stelle in der Eingabezeichenfolge angezeigt wird.

Windows XP, Windows Server 2003:

Wird nicht mehr unterstützt.

Die erforderliche Headerdatei und die DLL sind Teil der IDN-Entschärfungs-APIs (Microsoft Internationalized Domain Name), die nicht mehr zum Download verfügbar sind.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winnls.h (windows.h einschließen)
Bibliothek	Normaliz.lib
DLL	Normaliz.dll
Verteilbare Komponente	Microsoft Internationalized Domain Name (IDN) Mitigation APIs onWindows XP with SP2 and later,Windows Server 2003 with SP1

Weitere Informationen

Umgang mit internationalisierten Domänennamen (IDNs)

IdnToNameprepUnicode

IdnToUnicode

Unterstützung für landessprachliche Sprachen

Unterstützungsfunktionen für nationalsprachliche Sprachen

Freigeben über