Função GetStringScripts (winnls.h)

  • Artigo

Fornece uma lista de scripts usados na cadeia de caracteres Unicode especificada.

Sintaxe

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

Parâmetros

[in] dwFlags

Sinalizadores especificando opções para recuperação de script.

Valor Significado
GSS_ALLOW_INHERITED_COMMON
 Recupere informações de script "Qaii" (HERDADO) e "Zyyy" (COMMON). Esse sinalizador não afeta o processamento de caracteres não atribuídos. Esses caracteres na cadeia de caracteres de entrada sempre fazem com que um "Zzzz" (script UNASSIGNED) apareça na cadeia de caracteres de script.
 
Nota Por padrão, GetStringScripts ignora quaisquer caracteres herdados ou comuns na cadeia de caracteres de entrada indicada por lpString. Se GSS_ALLOW_INHERITED_COMMON não estiver definido, nem "Qaii" nem "Zyyy" aparecerão na cadeia de caracteres de script, mesmo que a cadeia de caracteres de entrada contenha esses caracteres. Se GSS_ALLOW_INHERITED_COMMON estiver definida e se a cadeia de caracteres de entrada contiver caracteres herdados e/ou comuns, "Qaii" e/ou "Zyyy", respectivamente, aparecerão na cadeia de caracteres de script. Consulte a seção Comentários.
 

[in] lpString

Ponteiro para a cadeia de caracteres Unicode a ser analisada.

[in] cchString

Tamanho, em caracteres, da cadeia de caracteres Unicode indicada por lpString. O aplicativo define esse parâmetro como -1 se a cadeia de caracteres Unicode for terminada em nulo. Se o aplicativo definir esse parâmetro como 0, a função recuperará uma cadeia de caracteres Unicode nula (L"\0") em lpScripts e retornará 1.

[out, optional] lpScripts

Ponteiro para um buffer no qual essa função recupera uma cadeia de caracteres terminada em nulo que representa uma lista de scripts, usando a notação de 4 caracteres usada no ISO 15924. Cada nome de script consiste em quatro caracteres latinos e os nomes são recuperados em ordem alfabética. Cada nome, incluindo o último, é seguido por um ponto e vírgula.

Como alternativa, esse parâmetro conterá NULL se cchScripts estiver definido como 0. Nesse caso, a função retorna o tamanho necessário para o buffer de script.

[in] cchScripts

Tamanho, em caracteres, do buffer de script indicado por lpScripts.

Como alternativa, o aplicativo pode definir esse parâmetro como 0. Nesse caso, a função recupera NULL em lpScripts e retorna o tamanho necessário para o buffer de script.

Retornar valor

Retorna o número de caracteres recuperados no buffer de saída, incluindo um caractere nulo de terminação, se bem-sucedido e cchScripts for definido como um valor diferente de zero. A função retorna 1 para indicar que nenhum script foi encontrado, por exemplo, quando a cadeia de caracteres de entrada contém apenas caracteres COMMON ou INHERITED e GSS_ALLOW_INHERITED_COMMON não está definida. Considerando que cada script encontrado adiciona cinco caracteres (quatro caracteres + delimitador), uma operação matemática simples fornece a contagem de scripts como (return_code - 1) / 5.

Se a função for bem-sucedida e o valor de cchScripts for 0, a função retornará o tamanho necessário, em caracteres, incluindo um caractere nulo de terminação, para o buffer de script. A contagem de scripts é conforme descrito acima.

Essa função retornará 0 se não for bem-sucedida. Para obter informações de erro estendidas, o aplicativo pode chamar GetLastError, que pode retornar um dos seguintes códigos de erro:

  • ERROR_BADDB. A função não pôde acessar os dados. Normalmente, essa situação não deve ocorrer e normalmente indica uma instalação incorreta, um problema de disco ou similar.
  • ERROR_INSUFFICIENT_BUFFER. Um tamanho de buffer fornecido não era grande o suficiente ou foi definido incorretamente como NULL.
  • 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.

Comentários

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

A determinação do script baseia-se nos valores de script publicados pelo Unicode Consortium em http://www.unicode.org/Public/4.1.0/ucd/Scripts.txt, exceto que os caracteres não atribuídos têm o valor "Zzzz" (UNASSIGNED) em vez de "Zyyy" (COMMON).

Aqui estão alguns exemplos do comportamento dessa função:

Cadeia de caracteres de entrada dwFlags lpScripts Scripts
Microsoft.com 0 Latn; Latim
Microsoft.com GSS_ALLOW_INHERITED_COMMON Latn; Zyyy; Latino + Comum
Niño 004E 0069 0241 006F GSS_ALLOW_INHERITED_COMMON Latn; Latim
Usa LATIN SMALL LETTER N WITH TILDE
Niño 004E 0069 006E 0303 006F GSS_ALLOW_INHERITED_COMMON Latn; Qaii; Latino + Herdado
Usa COMBINING TILDE
Spооf 0053 0070 043e 043e 0066 0 Latn; Cyrl; Latino + Cirílico
Usa CYRILLIC SMALL LETTER O
U+f000 0 Zzzz; Não atribuído
U+f000 GSS_ALLOW_INHERITED_COMMON Zzzz; Não atribuído

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

Confira também

DownlevelGetStringScripts

Manipulando IDNs (nomes de domínio internacionalizados)

Suporte a idiomas nacionais

Funções de suporte à linguagem nacional

VerifyScripts