Função DownlevelGetStringScripts

  • Artigo

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

Observação

Essa função é usada apenas por aplicativos executados em sistemas operacionais anteriores ao Windows Vista. Seu uso requer o pacote de download. Aplicativos que só são executados no Windows Vista e posteriores devem chamar GetStringScripts.

 

Sintaxe

int DownlevelGetStringScripts(
  _In_  DWORD   dwFlags,
  _In_  LPCWSTR lpString,
  _In_  int     cchString,
  _Out_ LPWSTR  lpScripts,
  _In_  int     cchScripts
);

Parâmetros

dwFlags [in]

Sinalizadores que especificam opções para recuperação de scripts.

Valor Significado
GSS_ALLOW_INHERITED_COMMON
 Recupere informações de script "Qaii" (HERDADO) e "Zyyy" (COMUM). Esse valor 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.

 

Observação

Por padrão, essa função ignora quaisquer caracteres herdados ou comuns na cadeia de caracteres Unicode de entrada. 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 definido e se a cadeia de caracteres de entrada contiver caracteres herdados e/ou comuns, "Qaii" e/ou "Zyyy" aparecerão na cadeia de caracteres de script. Consulte a seção Comentários.

 

lpString [in]

Ponteiro para a cadeia de caracteres Unicode a ser analisada.

cchString [in]

Tamanho, em caracteres, da cadeia de caracteres Unicode indicada por lpString. O aplicativo define esse parâmetro como -1 se a cadeia de caracteres terminar 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.

lpScripts [out]

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 na ISO 15924. Cada nome de script consiste em quatro caracteres latinos e os nomes são recuperados em ordem alfabética. Cada um deles, incluindo o último, é seguido por um ponto e vírgula.

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

cchScripts [in]

Tamanho, em caracteres, para o 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.

Valor retornado

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. Dado que cada script encontrado adiciona cinco caracteres (quatro caracteres + delimitador), uma operação matemática simples fornece a contagem de script como (return_code - 1) / 5.

Se a função for bem-sucedida e o valor de cchScripts for 0, o valor retornado será 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.

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

  • ERROR_BADDB. A função não pôde acessar os dados. Essa situação normalmente não deve ocorrer e geralmente indica uma instalação incorreta, um problema de disco ou algo 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 os 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 atenuar 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 Consórcio Unicode em https://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

${ROWSPAN2}$Niño${REMOVE}$

004E 0069 0241 006F

${ROWSPAN2}$GSS_ALLOW_INHERITED_COMMON${REMOVE}$

${ROWSPAN2}$Latn;${REMOVE}$

${ROWSPAN2}$Latin${REMOVE}$

Usa LETRA LATINA MINÚSCULA N COM TIL

${ROWSPAN2}$Ni ño${REMOVE}$

004E 0069 006E 0303 006F

${ROWSPAN2}$GSS_ALLOW_INHERITED_COMMON${REMOVE}$

${ROWSPAN2}$Latn; Qaii;${REMOVE}$

${ROWSPAN2}$Latin + Herdado ${REMOVE}$

Usa TIL DE COMBINAÇÃO

${ROWSPAN2}$Spооf${REMOVE}$

0053 0070 043e 043e 0066

${ROWSPAN2}$0${REMOVE}$

${ROWSPAN2}$Latn;Cyrl;${REMOVE}$

${ROWSPAN2}$Latin + Cyrillic${REMOVE}$

Usa LETRA O MINÚSCULA CIRÍLICA

U+f000

0

Zzzz;

Não atribuído

U+f000

GSS_ALLOW_INHERITED_COMMON

Zzzz;

Não atribuído

 

O arquivo de cabeçalho necessário e a DLL fazem parte do download das "APIs de Mitigação de IDN (Nome de Domínio Internacionalizado) da Microsoft", disponíveis no archive.org.

Requisitos

Requisito Valor
Cliente mínimo com suporte
 Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte
 Windows Server 2003 [somente aplicativos da área de trabalho]
Redistribuível
 APIs de mitigação do IDN (Nome de Domínio Internacionalizado) da Microsoft no Windows XP (SP2 ou posterior), Windows Server 2003 (SP1 ou posterior) ou Windows Vista
Cabeçalho
Idndl.h
DLL
Idndl.dll

Confira também

Suporte ao idioma nacional

Funções de suporte ao idioma nacional

Manipular IDNs (nomes de domínio internacionalizados)

DownlevelGetLocaleScripts

DownlevelVerifyScripts

GetStringScripts