NormalizeString-Funktion (winnls.h)

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

Syntax

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

Die Parameter

[in] NormForm

Zu verwendende Normalisierungsformular. NORM_FORM gibt die standardmäßigen Unicode-Normalisierungsformulare 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 wird und die Länge automatisch berechnet wird.

[out, optional] lpDstString

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

[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 zum Ausführen der tatsächlichen Konvertierung erforderlich ist.

Wenn die Zeichenfolge im Eingabepuffer null-terminated ist oder cwSrcLength -1 ist, ist die in den Zielpuffer geschriebene Zeichenfolge null-beendet, und die zurückgegebene Zeichenfolgenlänge enthält das endende Nullzeichen.

Die Funktion gibt einen Wert zurück, der kleiner oder gleich 0 ist, wenn er nicht erfolgreich ist. Um erweiterte Fehlerinformationen zu erhalten, kann die Anwendung GetLastErroraufrufen, wodurch eine 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. Ungültige Parameterwerte.
• ERROR_NO_UNICODE_TRANSLATION. Ungültiges Unicode wurde in einer Zeichenfolge gefunden. Der Rückgabewert ist der negative Index des Speicherorts des Fehlers in der Eingabezeichenfolge.
• ERROR_SUCCESS. Die Aktion wurde erfolgreich abgeschlossen, lieferte aber keine Ergebnisse.

Bemerkungen

Einige Unicode-Zeichen weisen mehrere gleichwertige binäre Darstellungen auf, 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. Normalisierung kann mit mehreren Algorithmen durchgeführt werden, die als Normalisierungsformulare bezeichnet werden, die unterschiedlichen Regeln entsprechen, wie unter Verwendung der Unicode-Normalisierung zum Darstellen von Zeichenfolgen beschrieben. Win32 und .NET Framework unterstützen derzeit Normalisierungsformulare C, D, KC und KD, wie in Unicode Standard Anhang Nr. 15: Unicode Normalisierungsformulare definiert. Normalisierte Zeichenfolgen werden in der Regel mit einem Ordinalvergleich 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 DLL sind Teil der MICROSOFT Internationalized Domain Name (IDN)-Entschärfungs-APIs, die nicht mehr zum Download verfügbar sind.

Examples

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

Anforderungen

Siehe auch

IsNormalizedString

NORM_FORM

Funktionen

Verwenden der Unicode-Normalisierung zur Darstellung von Zeichenfolgen