Função GetLocaleInfoEx (winnls.h)

Artigo
08/27/2023

Recupera informações sobre uma localidade especificada por nome.

Nota O aplicativo deve chamar essa função em preferência para GetLocaleInfo se projetado para ser executado somente no Windows Vista e posterior.

Nota Essa função pode recuperar dados que são alterados entre versões, por exemplo, devido a uma localidade personalizada. Se o aplicativo precisar persistir ou transmitir dados, consulte Usando dados de localidade persistente.

Sintaxe

int GetLocaleInfoEx(
  [in, optional]  LPCWSTR lpLocaleName,
  [in]            LCTYPE  LCType,
  [out, optional] LPWSTR  lpLCData,
  [in]            int     cchData
);

Parâmetros

[in, optional] lpLocaleName

Ponteiro para um nome de localidade ou um dos valores predefinidos a seguir.

[in] LCType

As informações de localidade a serem recuperadas. Para obter valores possíveis, consulte a seção "Constantes usadas no parâmetro LCType de GetLocaleInfo, GetLocaleInfoEx e SetLocaleInfo" em Constantes de informações de localidade. Observe que apenas uma parte das informações de localidade pode ser especificada por chamada.

O aplicativo pode usar o operador OR binário para combinar LOCALE_RETURN_NUMBER com qualquer outra constante permitida. Nesse caso, a função recupera o valor como um número em vez de uma cadeia de caracteres. O buffer que recebe o valor deve ter pelo menos o comprimento de um valor DWORD, que é 2.

Cuidado Também é possível combinar LOCALE_NOUSEROVERRIDE com qualquer outra constante. No entanto, o uso dessa constante é fortemente desencorajado. (Mesmo sem usar a substituição de usuário atual, os dados podem diferir de computador para computador e localidades personalizadas podem alterar os dados. Por exemplo, até mesmo nomes de mês ou dia estão sujeitos a reformas ortográficas.)

Se LCType estiver definido como LOCALE_IOPTIONALCALENDAR, a função recuperará apenas o primeiro calendário alternativo.

Nota Para obter todos os calendários alternativos, o aplicativo deve usar EnumCalendarInfoEx.

A partir do Windows Vista, seus aplicativos não devem usar LOCALE_ILANGUAGE no parâmetro LCType para evitar falhas ou recuperação de dados inesperados. Em vez disso, é recomendável que seus aplicativos chamem GetLocaleInfoEx.

[out, optional] lpLCData

Ponteiro para um buffer no qual essa função recupera as informações de localidade solicitadas. Esse ponteiro não será usado se cchData estiver definido como 0.

[in] cchData

Tamanho, em caracteres, do buffer de dados indicado por lpLCData. Como alternativa, o aplicativo pode definir esse parâmetro como 0. Nesse caso, a função não usa o parâmetro lpLCData e retorna o tamanho do buffer necessário, incluindo o caractere nulo de terminação.

Retornar valor

Retorna o número de caracteres recuperados no buffer de dados de localidade se bem-sucedido e cchData é um valor diferente de zero. Se a função for bem-sucedida, cchData será diferente de zero e LOCALE_RETURN_NUMBER for especificado, o valor retornado será o tamanho do inteiro recuperado no buffer de dados, ou seja, 2. Se a função for bem-sucedida e o valor de cchData for 0, o valor retornado será o tamanho necessário, em caracteres, incluindo um caractere nulo, para o buffer de dados de localidade.

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

ERROR_INSUFFICIENT_BUFFER. Um tamanho de buffer fornecido não era grande o suficiente ou estava definido incorretamente como NULL.
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

Essa função normalmente recupera informações no formato de texto. Se as informações forem um valor numérico e o valor de LCType for LOCALE_ILANGUAGE ou LOCALE_IDEFAULTLANGUAGE, essa função recuperará cadeias de caracteres que contêm números hexadecimais. Caso contrário, o texto recuperado para informações numéricas é um número decimal.

Há duas exceções a essa regra. Primeiro, o aplicativo pode recuperar valores numéricos como inteiros especificando LOCALE_RETURN_NUMBER no parâmetro LCType . A segunda exceção é que LOCALE_FONTSIGNATURE se comporta de forma diferente de todas as outras constantes de informações de localidade. O aplicativo deve fornecer um buffer de dados de pelo menos bytes sizeof(LOCALESIGNATURE). No retorno bem-sucedido da função, o buffer é preenchido como uma estrutura LOCALESIGNATURE .

Nota Mesmo quando o parâmetro LCType é especificado como LOCALE_FONTSIGNATURE, cchData e o retorno da função ainda são contagens de caracteres. Quando um aplicativo chama GetLocaleInfoEx com LCType especificado como LOCALE_FONTSIGNATURE, cchData pode ser especificado com segurança como sizeof(LOCALESIGNATURE) / sizeof(WCHAR).

Os exemplos a seguir lidam corretamente com o tamanho do buffer para valores que não são de texto:

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                      (LPWSTR)&value,
                      sizeof(value) / sizeof(WCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_FONTSIGNATURE,
                      (LPWSTR)&LocSig,
                      sizeof(LocSig) / sizeof(WCHAR) );

Essa função pode recuperar dados de localidades personalizadas. Não há garantia de que os dados sejam iguais de computador para computador ou entre execuções de um aplicativo. Se o aplicativo precisar persistir ou transmitir dados, consulte Usando dados de localidade persistente.

Começando no Windows 8: se o aplicativo passar marcas de idioma para essa função do namespace Windows.Globalization, ele deverá primeiro converter as marcas chamando ResolveLocaleName.

Exemplos

Exemplos que mostram o uso dessa função podem ser encontrados em NLS: Exemplo de APIs baseadas em nome e NLS: exemplo de mitigação de IDN (nome de domínio internacionalizado).

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winnls.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll