Função GetStringTypeA (winnls.h)

  • Artigo

Preterido. 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.

Cuidado Usar a função GetStringTypeA 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.

 

Sintaxe

BOOL GetStringTypeA(
  [in]  LCID   Locale,
  [in]  DWORD  dwInfoType,
  [in]  LPCSTR lpSrcStr,
  [in]  int    cchSrc,
  [out] LPWORD lpCharType
);

Parâmetros

[in] Locale

Identificador de localidade que especifica a localidade. 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 ANSI para a qual recuperar os tipos de caracteres. A cadeia de caracteres pode ser uma cadeia de caracteres de byte duplo (DBCS) se a localidade fornecida for apropriada para DBCS. 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. 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.

Retornar valor

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.

Essa 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 , GetStringTypeA é de uso limitado para cadeias de caracteres múltiplas. A função GetStringTypeW e GetStringTypeEx são recomendadas.

Quando essa 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.

O parâmetro Locale não é usado pela função GetStringTypeW correspondente. 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. Um aplicativo pode contornar essa limitação usando GetStringTypeEx, que é a função recomendada.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho winnls.h (inclua Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

GetStringTypeEx

GetStringTypeW

Suporte à linguagem nacional

Funções de suporte à linguagem nacional