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

Статья
03/08/2023

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

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

Синтаксис

int LCMapStringA(
  [in]            LCID   Locale,
  [in]            DWORD  dwMapFlags,
  [in]            LPCSTR lpSrcStr,
  [in]            int    cchSrc,
  [out, optional] LPSTR  lpDestStr,
  [in]            int    cchDest
);

Параметры

[in] Locale

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

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

[in] dwMapFlags

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

[in] lpSrcStr

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

[in] cchSrc

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

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

Приложение не может задать для этого параметра значение 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. Любое из значений параметров было недопустимым.

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

Примечание

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

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winnls.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll