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:

Requisitos

Confira também

DownlevelGetStringScripts

Manipulando IDNs (nomes de domínio internacionalizados)

Suporte a idiomas nacionais

Funções de suporte à linguagem nacional

VerifyScripts