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

Статья
08/27/2023

Для языкового стандарта, указанного идентификатором, сопоставляет одну входную строку символов с другой с помощью указанного преобразования или создает ключ сортировки для входной строки.

Примечание По соображениям взаимодействия приложение должно предпочесть функцию LCMapStringExLCMapString, так как корпорация Майкрософт переносится на использование имен языкового стандарта вместо идентификаторов языков для новых языков. Эта рекомендация особенно относится к пользовательским языковым стандартам, включая созданные корпорацией Майкрософт. Любое приложение, которое будет выполняться только в Windows Vista и более поздних версий, должно использовать LCMapStringEx.

Синтаксис

int LCMapStringW(
  [in]            LCID    Locale,
  [in]            DWORD   dwMapFlags,
  [in]            LPCWSTR lpSrcStr,
  [in]            int     cchSrc,
  [out, optional] LPWSTR  lpDestStr,
  [in]            int     cchDest
);

Параметры

[in] Locale

идентификатор языкового стандарта, указывающий языковой стандарт. Вы можете использовать макрос MAKELCID для создания идентификатора языкового стандарта или использования одного из следующих предопределенных значений.

Также поддерживаются следующие пользовательские идентификаторы языкового стандарта.

[in] dwMapFlags

Флаги, указывающие тип преобразования, используемый во время сопоставления строк или тип ключа сортировки для создания. Подробные определения см. в параметре dwMapFlags LCMapStringEx.

[in] lpSrcStr

Указатель на исходную строку, которую функция сопоставляет или использует для создания ключей сортировки. Эта строка не может иметь размер 0.

[in] cchSrc

Размер в символах исходной строки, указанной lpSrcStr. Размер исходной строки может включать завершающийся символ NULL, но не обязательно. Если включено завершающее значение NULL, поведение сопоставления функции не затрагивается, так как завершающий символ NULL считается неортизменяемым и всегда сопоставляется с собой.

Приложение может задать для параметра любое отрицательное значение, чтобы указать, что исходная строка завершается значением NULL. В этом случае, если LCMapString используется в режиме сопоставления строк, функция вычисляет сам строку и завершает сопоставленную строку, указанную lpDestStr.

Приложение не может задать для этого параметра значение 0.

[out, optional] lpDestStr

Указатель на буфер, в котором эта функция извлекает сопоставленную строку или ключ сортировки.

Если приложение использует функцию для создания ключа сортировки (LCMAP_SORTKEY):

Ключ сортировки хранится в буфере и обрабатывается как непрозрачный массив байтов. Сохраненные значения могут содержать внедренные 0 байтов в любой позиции.
Целевая строка может содержать нечетное число байтов. Флаг LCMAP_BYTEREV только изменяет четное число байтов. Последний байт (нечетный) в ключе сортировки не перевернут.

Если вызывающий объект явно запрашивает подмножество строки, целевая строка не включает завершающийся символ NULL, если вызывающий объект не указал его в cchDest.

Если эта функция завершается ошибкой, целевой буфер может содержать либо частичные результаты, либо нет ни одного результата. В этом случае все результаты должны считаться недействительными.

Заметка

При настройке LCMAP_UPPERCASE или LCMAP_LOWERCASE целевая строка может использовать тот же буфер, что и исходная строка. Однако это настоятельно не рекомендуется, так как некоторые условия могут привести к другой длине возвращаемой регистрной строки.

[in] cchDest

Размер в символах целевой строки, указанной lpDestStr. Если приложение использует функцию для сопоставления строк, она предоставляет число символов для этого параметра. Если пробел для завершающего символа NULL включен в cchSrc, cchDest также должно содержать пробел для конца символа NULL.

Если приложение использует функцию для создания ключа сортировки, оно предоставляет количество байтов для размера. Это число байтов должно содержать пробел для ключа сортировки 0x00 конца.

Приложение может задать cchDest значение 0. В этом случае функция не использует параметр lpDestStr и возвращает требуемый размер буфера для сопоставленной строки или ключа сортировки.

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

Если функция успешно выполняется при сопоставлении строк, она возвращает количество символов в преобразованной строке (дополнительные сведения см. в разделе cchSrc и cchDest).

Если функция завершается успешно при использовании для сопоставления строк, она возвращает количество байтов в ключе сортировки.

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

ERROR_INSUFFICIENT_BUFFER. Указанный размер буфера был недостаточно велик или неправильно задано значение NULL.
ERROR_INVALID_FLAGS. Значения, предоставленные для флагов, недопустимы.
ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.

ERROR_INSUFFICIENT_BUFFER. Указанный размер буфера был недостаточно велик или неправильно задано значение NULL.
ERROR_INVALID_FLAGS. Значения, предоставленные для флагов, недопустимы.
ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.

Замечания

См. примечания для LCMapStringEx.

Версия ANSI LCMapString сопоставляет строки с Юникодом на основе кодовой страницы Windows (ANSI), связанной с указанным языковым стандартом. При использовании версии ANSI этой функции с языковым стандартом Юникода функция может завершиться успешно, так как операционная система использует значение CP_ACP, представляющее кодовую страницу Windows ANSI по умолчанию по умолчанию. Однако символы, которые не определены в системной кодовой странице, отображаются в строке как вопросительный знак (?).

Заметка

Заголовок winnls.h определяет LCMapString как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winnls.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll