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

Статья
08/27/2023

Предоставляет список скриптов, используемых в указанной строке Юникода.

Синтаксис

int GetStringScripts(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpString,
  [in]            int     cchString,
  [out, optional] LPWSTR  lpScripts,
  [in]            int     cchScripts
);

Параметры

[in] dwFlags

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

Значение	Значение
GSS_ALLOW_INHERITED_COMMON	Получение сведений о скриптах "Qaii" (INHERITED) и "Zyyy" (COMMON). Этот флаг не влияет на обработку неназначенных символов. Эти символы во входной строке всегда приводят к отображению в строке скрипта Zzzz (UNASSIGNED).

Примечание По умолчанию GetStringScripts игнорирует все унаследованные или общие символы во входной строке, указанной lpString. Если GSS_ALLOW_INHERITED_COMMON не задано, в строке скрипта не отображается ни "Qaii", ни "Zyyy", даже если входная строка содержит такие символы. Если задано GSS_ALLOW_INHERITED_COMMON и если входная строка содержит унаследованные и (или) общие символы, в строке скрипта отображаются "Qaii" и (или) "Zyyy", соответственно. См. раздел «Примечания».

[in] lpString

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

[in] cchString

Размер (в символах) строки Юникода, указанной lpString. Приложение задает этому параметру значение -1, если строка Юникода завершается null. Если приложение задает этому параметру значение 0, функция получает пустую строку Юникода (L"\0") в lpScripts и возвращает значение 1.

[out, optional] lpScripts

Указатель на буфер, в котором эта функция извлекает строку со значением NULL, представляющую список скриптов, используя 4-символьную нотацию, используемую в СТАНДАРТЕ ISO 15924. Каждое имя скрипта состоит из четырех латинских символов, и имена извлекаются в алфавитном порядке. За каждым именем, включая последнее, следует точка с запятой.

Кроме того, этот параметр содержит значение NULL , если cchScripts имеет значение 0. В этом случае функция возвращает необходимый размер для буфера скрипта.

[in] cchScripts

Размер буфера скрипта в символах, указанный lpScripts.

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

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

Возвращает число символов, извлеченных в выходном буфере, включая завершающий символ NULL, если успешно и cchScripts имеет ненулевое значение. Функция возвращает значение 1, чтобы указать, что скрипт не найден, например, если входная строка содержит только символы COMMON или INHERITED, а GSS_ALLOW_INHERITED_COMMON не задан. Учитывая, что каждый найденный скрипт добавляет пять символов (четыре символа + разделитель), простая математическая операция предоставляет число скриптов как (return_code – 1) / 5.

Если функция выполняется успешно и значение cchScripts равно 0, функция возвращает необходимый размер в символах, включая завершающий символ NULL, для буфера скрипта. Число скриптов, как описано выше.

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

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

Определение скрипта основано на значениях скриптов, опубликованных консорциумом Юникода в http://www.unicode.org/Public/4.1.0/ucd/Scripts.txt, за исключением того, что неназначенные символы имеют значение "Zzzz" (UNASSIGNED) вместо "Zyyyy" (COMMON).

Ниже приведены некоторые примеры поведения этой функции:

Входная строка		dwFlags	lpScripts	Скрипты
Microsoft.com		0	Латн;	Латиница
Microsoft.com		GSS_ALLOW_INHERITED_COMMON	Латн; Зийы;	Латинский + общий
Ниньо	004E 0069 0241 006F	GSS_ALLOW_INHERITED_COMMON	Латн;	Латиница
Ниньо	Использует ЛАТИНСКУЮ МАЛЕНЬКУЮ БУКВУ N С ТИЛЬДОЙ	GSS_ALLOW_INHERITED_COMMON	Латн;	Латиница
Ниньо	004E 0069 006E 0303 006F	GSS_ALLOW_INHERITED_COMMON	Латн; Qaii;	Латинский + Наследуемый
Ниньо	Используется COMBINING TILDE	GSS_ALLOW_INHERITED_COMMON	Латн; Qaii;	Латинский + Наследуемый
Spооf	0053 0070 043e 043e 0066	0	Латн; Cyrl;	Латиница + кириллица
Spооf	Использует КИРИЛЛИЦУ С МАЛЕНЬКОЙ БУКВОЙ O	0	Латн; Cyrl;	Латиница + кириллица
	U+f000	0	Zzzz;	"Не присвоено"
	U+f000	GSS_ALLOW_INHERITED_COMMON	Zzzz;	"Не присвоено"

Требования

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

См. также

DownlevelGetStringScripts

Обработка международных доменных имен (IDN)

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

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

VerifyScripts