Функция LCMapStringA (winnls.h)
Для языкового стандарта, указанного идентификатором, сопоставляет одну входную строку символов с другой с помощью указанного преобразования или создает ключ сортировки для входной строки.
Синтаксис
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. Любое из значений параметров было недопустимым.
Комментарии
См. примечания для LCMapStringEx.
Версия 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 |