Функция GetStringTypeExW (stringapiset.h)

Статья
08/26/2023

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

Осторожностью Неправильное использование функции GetStringTypeEx может поставить под угрозу безопасность приложения. Чтобы избежать переполнения буфера, приложение должно правильно задать размер выходного буфера. Дополнительные сведения о безопасности см. в разделе Вопросы безопасности: пользовательский интерфейс Windows.

Примечание В отличие от своих близких родственников GetStringTypeA и GetStringTypeW, эта функция демонстрирует соответствующее поведение ANSI или Юникод за счет использования #define переключателя ЮНИКОД. Это рекомендуемая функция для извлечения символьного типа.

Синтаксис

BOOL GetStringTypeExW(
  [in]  LCID                          Locale,
  [in]  DWORD                         dwInfoType,
  [in]  _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]  int                           cchSrc,
  [out] LPWORD                        lpCharType
);

Параметры

[in] Locale

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

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

[in] dwInfoType

Флаги, указывающие извлекаемую информацию о типе символов. Возможные значения флагов см. в параметре dwInfoTypeэлемента GetStringTypeW. Подробные сведения о битах символьного типа см. в разделе Примечания для GetStringTypeW.

[in] lpSrcStr

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

[in] cchSrc

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

[out] lpCharType

Указатель на массив 16-разрядных значений. Длина этого массива должна быть достаточно большой, чтобы получить одно 16-разрядное значение для каждого символа в исходной строке. Если cchSrc не является отрицательным числом, lpCharType должен быть массивом слов с элементами cchSrc . Если для cchSrc задано отрицательное число, lpCharType — это массив слов с элементами lpSrcStr + 1. При возврате функции этот массив содержит по одному слову, соответствующему каждому символу в исходной строке.

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

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

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

Используя кодовую страницу ANSI для указанного языкового стандарта, эта функция преобразует исходную строку из ANSI в Юникод. Затем он анализирует каждый символ Юникода на предмет сведений о типе символов.

Версия ANSI этой функции преобразует исходную строку в Юникод и вызывает соответствующую функцию GetStringTypeW . Таким образом, слова в выходном буфере соответствуют не исходной строке ANSI, а ее эквиваленту в Юникоде. Преобразование из ANSI в Юникод может привести к изменению длины строки, например, пара символов ANSI может сопоставляться с одним символом Юникода. Таким образом, соответствие между словами в выходном буфере и символами в исходной строке ANSI не является "один к одному" во всех случаях, например в многобайтовых строках. Таким образом, версия ANSI этой функции используется ограниченно для многосимвуционных строк. Вместо этого рекомендуется использовать версию функции в Юникоде.

Эта функция обходит ограничение, вызванное разницей в параметрах между GetStringTypeA и GetStringTypeW. Из-за различий в параметрах приложение не может автоматически вызвать соответствующую версию ANSI или Юникод функции GetStringType* , используя параметр #DEFINE ЮНИКОД. С другой стороны, GetStringTypeEx правильно работает в отношении этого переключателя. Таким образом, это рекомендуемая функция.

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

Значения параметров lpSrcStr и lpCharType не должны совпадать. Если они совпадают, функция завершается сбоем с ERROR_INVALID_PARAMETER.

Параметр Locale используется только для преобразования строк в Юникод. Он не имеет ничего общего со значениями CTYPE*, предоставленными приложением. Эти значения определяются исключительно кодовых точками Юникода и не зависят от языкового стандарта. Например, греческие буквы указываются как C1_ALPHA для любого значения Locale.

Требования


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

См. также

GetStringTypeW

Поддержка национальных языков

Функции поддержки национальных языков