Função GetStringTypeExW (stringapiset.h)

Artigo
11/20/2024

Nota

Essa API pode ter informações incompletas/desatualizadas para determinados caracteres Unicode, especialmente aqueles no intervalo suplementar. Para obter informações de tipo de caractere Unicode mais precisas e abrangentes, considere o uso de APIs de UTI equivalentes, como u_charType, u_islower, u_isspacee u_ispunct. Para obter diretrizes sobre como usar APIs de UTI no Windows, consulte Introdução à UTI no Windows.

Recupera informações de tipo de caractere para os caracteres na cadeia de caracteres de origem especificada. Para cada caractere na cadeia de caracteres, a função define um ou mais bits no elemento de 16 bits correspondente da matriz de saída. Cada bit identifica um determinado tipo de caractere, por exemplo, letra, dígito ou nenhum deles.

Cuidado Usar a função GetStringTypeEx incorretamente pode comprometer a segurança do aplicativo. Para evitar um estouro de buffer, o aplicativo deve definir o tamanho do buffer de saída corretamente. Para obter mais informações de segurança, consulte Considerações de segurança: interface do usuário do Windows.

Observação Diferentemente de seus parentes próximos getStringTypeA e GetStringTypeW, essa função exibe o comportamento apropriado de ANSI ou Unicode por meio do uso do comutador UNICODE #define. Essa é a função recomendada para recuperação de tipo de caractere.

Sintaxe

BOOL GetStringTypeExW(
  [in]  LCID                          Locale,
  [in]  DWORD                         dwInfoType,
  [in]  _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]  int                           cchSrc,
  [out] LPWORD                        lpCharType
);

Parâmetros

[in] Locale

identificador de localidade que especifica a localidade. Esse valor define exclusivamente a página de código ANSI. Você pode usar a macro MAKELCID para criar um identificador de localidade ou usar um dos seguintes valores predefinidos.

Windows Vista e posterior: Também há suporte para os seguintes identificadores de localidade personalizados.

[in] dwInfoType

Sinalizadores especificando as informações de tipo de caractere a serem recuperadas. Para obter valores de sinalizador possíveis, consulte o parâmetro dwInfoType de GetStringTypeW. Para obter informações detalhadas sobre os bits de tipo de caractere, consulte Comentários para GetStringTypeW.

[in] lpSrcStr

Ponteiro para a cadeia de caracteres para a qual recuperar os tipos de caractere. Supõe-se que a cadeia de caracteres seja terminada em nulo se cchSrc for definido como qualquer valor negativo.

[in] cchSrc

Tamanho, em caracteres, da cadeia de caracteres indicada por lpSrcStr. O tamanho refere-se a bytes para a versão ANSI da função ou caracteres largos para a versão Unicode. Se o tamanho incluir um caractere nulo de encerramento, a função recuperará informações de tipo de caractere para esse caractere. Se o aplicativo definir o tamanho como qualquer inteiro negativo, a cadeia de caracteres de origem será considerada terminada em nulo e a função calculará o tamanho automaticamente com um caractere adicional para a terminação nula.

[out] lpCharType

Ponteiro para uma matriz de valores de 16 bits. O comprimento dessa matriz deve ser grande o suficiente para receber um valor de 16 bits para cada caractere na cadeia de caracteres de origem. Se cchSrc não for um número negativo, lpCharType deverá ser uma matriz de palavras com elementos cchSrc . Se cchSrc for definido como um número negativo, lpCharType será uma matriz de palavras com lpSrcStr + 1 elementos. Quando a função retorna, essa matriz contém uma palavra correspondente a cada caractere na cadeia de caracteres de origem.

Valor de retorno

Retorna um valor diferente de zero se tiver êxito ou 0 de outra forma. Para obter informações de erro estendidas, o aplicativo pode 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.

Observações

Para obter uma visão geral do uso das funções de cadeia de caracteres, consulte Strings.

Usando a página de código ANSI para a localidade fornecida, essa função converte a cadeia de caracteres de origem de ANSI para Unicode. Em seguida, ele analisa cada caractere Unicode para obter informações de tipo de caractere.

A versão ANSI dessa função converte a cadeia de caracteres de origem em Unicode e chama a função GetStringTypeW correspondente. Portanto, as palavras no buffer de saída não correspondem à cadeia de caracteres ANSI original, mas ao seu equivalente Unicode. A conversão de ANSI para Unicode pode resultar em uma alteração no comprimento da cadeia de caracteres, por exemplo, um par de caracteres ANSI pode ser mapeado para um único caractere Unicode. Portanto, a correspondência entre as palavras no buffer de saída e os caracteres na cadeia de caracteres ANSI original não é um para um em todos os casos, por exemplo, cadeias de caracteres de váriosbytes. Portanto, a versão ANSI dessa função é de uso limitado para cadeias de caracteres múltiplas. Em vez disso, a versão Unicode da função é recomendada.

Essa função contorna uma limitação causada pela diferença de parâmetros entre GetStringTypeA e GetStringTypeW. Devido à diferença de parâmetro, um aplicativo não pode invocar automaticamente a versão ANSI ou Unicode adequada de uma função GetStringType* por meio do uso do comutador UNICODE #define. Por outro lado, GetStringTypeEx se comporta corretamente em relação a essa opção. Portanto, é a função recomendada.

Quando a versão ANSI dessa função é usada com um identificador de localidade somente Unicode, a função pode ser bem-sucedida porque o sistema operacional usa a página de código do sistema. No entanto, caracteres que são indefinidos na página de código do sistema aparecem na cadeia de caracteres como um ponto de interrogação (?).

Os valores dos parâmetros lpSrcStr e lpCharType não devem ser os mesmos. Se forem iguais, a função falhará com ERROR_INVALID_PARAMETER.

O parâmetro Locale é usado apenas para executar a conversão de cadeia de caracteres em Unicode. Não tem nada a ver com os valores CTYPE* fornecidos pelo aplicativo. Esses valores são determinados apenas por pontos de código Unicode e não variam de acordo com a localidade. Por exemplo, as letras gregas são especificadas como C1_ALPHA para qualquer valor de Locale.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows 2000 Server [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	stringapiset.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

GetStringTypeW

de Suporte à Linguagem Nacional

funções de suporte à linguagem nacional

Compartilhar via