Função GetStringTypeW (stringapiset.h)

Recupera informações de tipo de caractere para os caracteres na cadeia de caracteres de origem Unicode 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 GetStringTypeW(
  [in]  DWORD                         dwInfoType,
  [in]  _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]  int                           cchSrc,
  [out] LPWORD                        lpCharType
);

Parâmetros

[in] dwInfoType

Sinalizadores especificando as informações de tipo de caractere a serem recuperadas. Esse parâmetro pode ter os valores a seguir. Os tipos de caractere são divididos em diferentes níveis, conforme descrito na seção Comentários.

[in] lpSrcStr

Ponteiro para a cadeia de caracteres Unicode 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. 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.

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 pela função GetStringTypeA correspondente não é usado por essa função. 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.

Tipos de caracteres com suporte

Os bits de tipo de caractere são divididos em vários níveis. As informações de um nível podem ser recuperadas por uma única chamada para essa função. Cada nível é limitado a 16 bits de informações para que as outras funções de mapeamento, limitadas a 16 bits de representação por caractere, também possam retornar informações de tipo de caractere.

Ctype 1

Esses tipos dão suporte a funções de digitação de caracteres ANSI C e POSIX (LC_CTYPE). Um OR bit a bit desses valores é recuperado na matriz no buffer de saída quando dwInfoType é definido como CT_CTYPE1. Para localidades DBCS, os atributos de tipo se aplicam a caracteres estreitos e caracteres largos. Os caracteres hiragana e katakana japoneses e os caracteres ideógrafos kanji têm o atributo C1_ALPHA.

Os tipos de caracteres a seguir são constantes ou computáveis de tipos básicos e não precisam ter suporte nessa função.

Ctype 2

Esses tipos dão suporte ao layout adequado do texto Unicode. Para localidades DBCS, o tipo de caractere se aplica a caracteres estreitos e largos. Os atributos de direção são atribuídos para que o algoritmo de layout bidirecional padronizado pelo Unicode produza resultados precisos. Esses tipos são mutuamente exclusivos. Para obter mais informações sobre o uso desses atributos, consulte O Padrão Unicode.

Ctype 3

Esses tipos destinam-se a ser espaços reservados para extensões para os tipos POSIX necessários para processamento geral de texto ou para as funções de biblioteca C padrão. Um OR bit a bit desses valores é recuperado quando dwInfoType é definido como CT_CTYPE3. Para localidades DBCS, os atributos Ctype 3 se aplicam a caracteres estreitos e caracteres largos. Os caracteres hiragana e katakana japoneses e os caracteres ideógrafos kanji têm o atributo C3_ALPHA.

C3_HIGHSURROGATE e C3_LOWSURROGATE são listados apenas para integridade e nunca devem ser fornecidos a essa função. Eles são relevantes apenas para Unicode.

Começando com Windows 8: GetStringTypeW é declarado em Stringapiset.h. Antes de Windows 8, ele foi declarado em Winnls.h.

Requisitos

Confira também

GetStringTypeA

GetStringTypeEx

Suporte a idiomas nacionais

Funções de suporte à linguagem nacional