NormalizeString-Funktion (winnls.h)

Artikel
08/27/2023

Normalisiert Zeichen einer Textzeichenfolge gemäß Unicode 4.0 TR#15. Weitere Informationen finden Sie unter Verwenden der Unicode-Normalisierung zum Darstellen von Zeichenfolgen.

Syntax

int NormalizeString(
  [in]            NORM_FORM NormForm,
  [in]            LPCWSTR   lpSrcString,
  [in]            int       cwSrcLength,
  [out, optional] LPWSTR    lpDstString,
  [in]            int       cwDstLength
);

Parameter

[in] NormForm

Zu verwendende Normalisierungsformular. NORM_FORM gibt die Unicode-Standardnormalisierungsformulare an.

[in] lpSrcString

Zeiger auf die nicht normalisierte Quellzeichenfolge.

[in] cwSrcLength

Länge des Puffers, der die Quellzeichenfolge enthält, in Zeichen. Die Anwendung kann diesen Parameter auf -1 festlegen, wenn die Funktion davon ausgehen soll, dass die Zeichenfolge null-beendet ist und die Länge automatisch berechnet wird.

[out, optional] lpDstString

Zeiger auf einen Puffer, in dem die Funktion die Zielzeichenfolge abruft. Alternativ enthält dieser Parameter NULL , wenn cwDstLength auf 0 festgelegt ist.

Hinweis Die Funktion beendet die Zeichenfolge nicht mit NULL, wenn die Eingabezeichenfolgenlänge explizit ohne beendendes NULL-Zeichen angegeben wird. Um die Ausgabezeichenfolge mit NULL zu beenden, sollte die Anwendung -1 angeben oder explizit das beendende NULL-Zeichen für die Eingabezeichenfolge zählen.

[in] cwDstLength

Länge des Puffers, der die Zielzeichenfolge enthält, in Zeichen. Alternativ kann die Anwendung diesen Parameter auf 0 festlegen, um die Funktion anzufordern, die erforderliche Größe für den Zielpuffer zurückzugeben.

Rückgabewert

Gibt die Länge der normalisierten Zeichenfolge im Zielpuffer zurück. Wenn cwDstLength auf 0 festgelegt ist, gibt die Funktion die geschätzte Pufferlänge zurück, die für die tatsächliche Konvertierung erforderlich ist.

Wenn die Zeichenfolge im Eingabepuffer NULL-beendet ist oder cwSrcLength -1 ist, ist die in den Zielpuffer geschriebene Zeichenfolge NULL-beendet, und die zurückgegebene Zeichenfolgenlänge enthält das beendende NULL-Zeichen.

Die Funktion gibt einen Wert zurück, der kleiner oder gleich 0 ist, wenn er nicht erfolgreich ist. Um erweiterte Fehlerinformationen abzurufen, 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_PARAMETER. Jeder der Parameterwerte war ungültig.
ERROR_NO_UNICODE_TRANSLATION. Ungültiger Unicode wurde in einer Zeichenfolge gefunden. Der Rückgabewert ist das Negative des Indexes der Position des Fehlers in der Eingabezeichenfolge.
ERROR_SUCCESS. Die Aktion wurde erfolgreich abgeschlossen, lieferte aber keine Ergebnisse.

Hinweise

Einige Unicode-Zeichen verfügen über mehrere gleichwertige binäre Darstellungen, die aus Kombinations- und/oder zusammengesetzten Unicode-Zeichen bestehen. Der Unicode-Standard definiert einen Prozess namens Normalisierung, der eine binäre Darstellung zurückgibt, wenn eine der entsprechenden binären Darstellungen eines Zeichens angegeben wird. Die Normalisierung kann mit mehreren Algorithmen durchgeführt werden, die als Normalisierungsformulare bezeichnet werden, die unterschiedlichen Regeln entsprechen, wie unter Verwenden der Unicode-Normalisierung zum Darstellen von Zeichenfolgen beschrieben. Win32 und die .NET Framework unterstützen derzeit die Normalisierungsformulare C, D, KC und KD, wie in Unicode Standard Annex 15: Unicode Normalization Forms definiert. Normalisierte Zeichenfolgen werden in der Regel mit einem Ordnungsvergleich ausgewertet.

Der folgende Code veranschaulicht die Verwendung der Pufferlängenschätzung:

const int maxIterations = 10;
LPWSTR strResult = NULL;
HANDLE hHeap = GetProcessHeap();

int iSizeEstimated = NormalizeString(form, strInput, -1, NULL, 0);
for (int i = 0; i < maxIterations; i++)
{
    if (strResult)
        HeapFree(hHeap, 0, strResult);
    strResult = (LPWSTR)HeapAlloc(hHeap, 0, iSizeEstimated * sizeof (WCHAR));
    iSizeEstimated = NormalizeString(form, strInput, -1, strResult, iSizeEstimated);
 
    if (iSizeEstimated > 0)
        break; // success 
 
    if (iSizeEstimated <= 0)
    {
        DWORD dwError = GetLastError();
        if (dwError != ERROR_INSUFFICIENT_BUFFER) break; // Real error, not buffer error 
 
        // New guess is negative of the return value. 
        iSizeEstimated = -iSizeEstimated;
    }
}

Windows XP, Windows Server 2003:

Wird nicht mehr unterstützt.

Die erforderliche Headerdatei und die DLL sind Teil der IDN-ApIs (Microsoft Internationalized Domain Name) zur Bekämpfung von Domänennamen, die nicht mehr zum Download verfügbar sind.

Beispiele

Ein Beispiel für die Verwendung dieser Funktion finden Sie in NLS: Unicode-Normalisierungsbeispiel.

Anforderungen


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 (einschließlich Windows.h)
DLL	Normaliz.dll
Verteilbare Komponente	Microsoft Internationalized Domain Name (IDN) Mitigation-APIs unterWindows XP mit SP2 und höher oderWindows Server 2003 mit SP1