Функция NormalizeString (winnls.h)

Статья
08/27/2023

Нормализует символы текстовой строки в соответствии с Юникодом 4.0 TR#15. Дополнительные сведения см. в разделе Использование нормализации Юникода для представления строк.

Синтаксис

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

Параметры

[in] NormForm

Используемая форма нормализации. NORM_FORM задает стандартные формы нормализации Юникода.

[in] lpSrcString

Указатель на ненормализованную исходную строку.

[in] cwSrcLength

Длина (в символах) буфера, содержащего исходную строку. Приложение может задать для этого параметра значение -1, если функция должна предполагать, что строка завершается null и вычислять длину автоматически.

[out, optional] lpDstString

Указатель на буфер, в котором функция извлекает строку назначения. Кроме того, этот параметр содержит значение NULL , если параметр cwDstLength имеет значение 0.

Примечание Функция не завершает строку со значением NULL, если длина входной строки явно указана без завершающего символа NULL. Чтобы завершить выходную строку со значением NULL, приложение должно указать -1 или явно подсчитать завершающий символ NULL для входной строки.

[in] cwDstLength

Длина (в символах) буфера, содержащего целевую строку. Кроме того, приложение может присвоить этому параметру значение 0, чтобы запросить у функции возврат требуемого размера для буфера назначения.

Возвращаемое значение

Возвращает длину нормализованной строки в буфере назначения. Если cwDstLength имеет значение 0, функция возвращает предполагаемую длину буфера, необходимую для фактического преобразования.

Если строка во входном буфере заканчивается null или cwSrcLength имеет значение -1, строка, записанная в буфер назначения, завершается null, а возвращаемая длина строки содержит завершающий символ NULL.

Функция возвращает значение, которое меньше или равно 0, если она не выполняется успешно. Чтобы получить расширенные сведения об ошибке, приложение может вызвать Метод GetLastError, который может возвращать один из следующих кодов ошибок:

ERROR_INSUFFICIENT_BUFFER. Указанный размер буфера был недостаточно велик или для него неправильно задано значение NULL.
ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.
ERROR_NO_UNICODE_TRANSLATION. В строке обнаружен недопустимый Юникод. Возвращаемое значение является отрицательным значением индекса расположения ошибки во входной строке.
ERROR_SUCCESS. Действие успешно завершено, но не дало результатов.

Некоторые символы Юникода имеют несколько эквивалентных двоичных представлений, состоящих из наборов комбинирующих и (или) составных символов Юникода. Стандарт Юникода определяет процесс, называемый нормализацией, который возвращает одно двоичное представление при наличии любого из эквивалентных двоичных представлений символа. Нормализация может выполняться с помощью нескольких алгоритмов, называемых формами нормализации, которые подчиняются разным правилам, как описано в разделе Использование нормализации Юникода для представления строк. Win32 и платформа .NET Framework в настоящее время поддерживают формы нормализации C, D, KC и KD, как определено в стандартном приложении Юникода No 15: формы нормализации Юникода. Нормализованные строки обычно оцениваются с помощью порядкового сравнения.

В следующем коде показано использование оценки длины буфера:

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:

Больше не поддерживается.

Необходимый файл заголовка и библиотека DLL являются частью API-интерфейсов устранения международных доменных имен (IDN) Майкрософт, которые больше не доступны для скачивания.

Примеры

Пример использования этой функции можно найти в разделе NLS: пример нормализации Юникода.

Требования


Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winnls.h (включая Windows.h)
DLL	Normaliz.dll
Распространяемые компоненты	API-интерфейсы устранения международных доменных имен (IDN) Майкрософт в Windows XP с пакетом обновления 2 (SP2) или Windows Server 2003 с пакетом обновления 1 (SP1)