Função GetStringScripts (winnls.h)
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.
[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
Manipulando IDNs (nomes de domínio internacionalizados)