Função VerifyScripts (winnls.h)

Artigo
08/27/2023

Compara duas listas enumeradas de scripts.

Sintaxe

BOOL VerifyScripts(
  [in] DWORD   dwFlags,
  [in] LPCWSTR lpLocaleScripts,
  [in] int     cchLocaleScripts,
  [in] LPCWSTR lpTestScripts,
  [in] int     cchTestScripts
);

Parâmetros

[in] dwFlags

Sinalizadores que especificam opções de verificação de script.

Valor	Significado
VS_ALLOW_LATIN	Permita "Latn" (script latino) na lista de testes, mesmo que não esteja na lista de localidades.

[in] lpLocaleScripts

Ponteiro para a lista de localidades, a lista enumerada de scripts para uma determinada localidade. Normalmente, essa lista é preenchida chamando GetLocaleInfoEx com LCType definido como LOCALE_SSCRIPTS.

[in] cchLocaleScripts

Tamanho, em caracteres, da cadeia de caracteres indicada por lpLocaleScripts. O aplicativo define esse parâmetro como -1 se a cadeia de caracteres for terminada em nulo. Se esse parâmetro for definido como 0, a função falhará.

[in] lpTestScripts

Ponteiro para a lista de testes, uma segunda lista enumerada de scripts. Normalmente, essa lista é preenchida chamando GetStringScripts.

[in] cchTestScripts

Tamanho, em caracteres, da cadeia de caracteres indicada por lpTestScripts. O aplicativo define esse parâmetro como -1 se a cadeia de caracteres for terminada em nulo. Se esse parâmetro for definido como 0, a função falhará.

Retornar valor

Retornará TRUE se a lista de testes não estiver vazia e todos os itens na lista também estiverem incluídos na lista de localidades. A função ainda retornará TRUE se a lista de localidades contiver mais scripts do que a lista de testes, mas todos os scripts da lista de testes deverão estar contidos na lista de localidades. Se VS_ALLOW_LATIN for especificado em dwFlags, a função se comportará como se "Latn;" estivesse sempre na lista de localidades.

Em todos os outros casos, a função retorna FALSE. Esse retorno pode indicar que a lista de testes contém um item que não está na lista de localidades ou pode indicar um erro. Para distinguir entre esses dois casos, o aplicativo deve chamar GetLastError, que pode retornar um dos seguintes códigos de erro:

ERROR_INVALID_FLAGS. Os valores fornecidos para sinalizadores não eram válidos.
ERROR_INVALID_PARAMETER. Qualquer um dos valores de parâmetro era inválido.
ERROR_SUCCESS. A ação foi concluída com êxito, mas não rendeu resultados.

Comentários

Essa função compara cadeias de caracteres, como "Latn; Cyrl;", que consiste em uma série de nomes de script de 4 caracteres, com cada nome de script seguido por ponto e vírgula. Ele também tem um caso especial para considerar o fato de que o script latino é frequentemente usado em idiomas e localidades para os quais ele não é nativo.

Essa função é útil como parte de uma estratégia para atenuar problemas de segurança relacionados a IDNs (nomes de domínio internacionalizados).

Veja a seguir exemplos do retorno dessa função e uma chamada subsequente para GetLastError em vários cenários. Os dois últimos exemplos ilustram, respectivamente, um caso em que a lista de testes não tem um ponto e vírgula de terminação (cadeia de caracteres malformada) e um caso em que a lista de testes está vazia.

Cadeia de caracteres de localidade	Cadeia de caracteres de teste	dwFlags	Retornar valor	Retorno de GetLastError
Hani; Hira; Kana;	Hani;	*	TRUE	(inalterado)
Hani; Hira; Kana;	Hani; Latn;	0	FALSE	ERROR_SUCCESS
Hani; Hira; Kana;	Hani; Latn;	VS_ALLOW_LATIN	TRUE	(inalterado)
Hani; Hira; Kana;	Cyrl;	*	FALSE	ERROR_SUCCESS
Hani;	Hani; Hira; Kana;	*	FALSE	ERROR_SUCCESS
Hani; Hira; Kana;	Cyrl	*	FALSE	ERROR_INVALID_PARAMETER
Hani; Hira; Kana;		*	TRUE	(inalterado)

Os resultados são os mesmos se VS_ALLOW_LATIN é passado no parâmetro dwFlags ou se nenhum sinalizador é fornecido.

Exemplos

NLS: Exemplo de mitigação de IDN (Nome de Domínio Internacionalizado) demonstra o uso dessa função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winnls.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll