Função GetStringTypeExW (stringapiset.h)
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 correspondente de 16 bits da matriz de saída. Cada bit identifica um determinado tipo de caractere, por exemplo, letra, dígito ou nenhum deles.
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 caracteres. Presume-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 terminação, 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 elementos lpSrcStr + 1. Quando a função retorna, essa matriz contém uma palavra correspondente a cada caractere na cadeia de caracteres de origem.
Valor retornado
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.
Comentários
Para obter uma visão geral do uso das funções de cadeia de caracteres, consulte Cadeias de caracteres.
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 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 mapear 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 multibyte. 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 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 só é usado para executar a conversão de cadeia de caracteres em Unicode. Ele não tem nada a ver com os valores CTYPE* fornecidos pelo aplicativo. Esses valores são determinados exclusivamente 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
| Cliente mínimo com suporte | Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | stringapiset.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |