Função GetLocaleInfoA (winnls.h)

Artigo
08/27/2023

Recupera informações sobre uma localidade especificada pelo identificador.

Nota Por motivos de interoperabilidade, o aplicativo deve preferir a função GetLocaleInfoEx a GetLocaleInfo porque a Microsoft está migrando para o uso de nomes de localidade em vez de identificadores de localidade para novas localidades. Qualquer aplicativo executado somente no Windows Vista e posterior deve usar GetLocaleInfoEx.

Nota Para compatibilidade global, o aplicativo deve preferir os formulários de API "W" Unicode aos formulários "A". GetLocaleInfoA limitará os dados de caracteres e poderá resultar em resultados que parecem corrompidos para os usuários, especialmente em aplicativos habilitados globalmente. Para essa API, GetLocaleInfoEx é preferencial, pois é Unicode e também dá suporte a padrões de nome de localidade modernos.

Sintaxe

int GetLocaleInfoA(
  [in]            LCID   Locale,
  [in]            LCTYPE LCType,
  [out, optional] LPSTR  lpLCData,
  [in]            int    cchData
);

Parâmetros

[in] Locale

Identificador de localidade para o qual recuperar informações. Você pode usar a macro MAKELCID para criar um identificador de localidade ou usar um dos seguintes valores predefinidos.

[in] LCType

As informações de localidade a serem recuperadas. Para obter definições detalhadas, consulte o parâmetro LCType de GetLocaleInfoEx.

Nota Para GetLocaleInfo, o valor LOCALE_USE_CP_ACP é relevante apenas para a versão ANSI.

[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. Para obter mais informações, consulte a seção Comentários.

[in] cchData

Tamanho, em valores TCHAR, 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.

Valor retornado

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 não será zero e LOCALE_RETURN_NUMBER for especificado, o valor retornado será o tamanho do inteiro recuperado no buffer de dados; ou seja, 2 para a versão Unicode da função ou 4 para a versão ANSI. 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 foi 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

Para a operação dessa função, consulte Comentários para GetLocaleInfoEx.

Nota Mesmo quando o parâmetro LCType é especificado como LOCALE_FONTSIGNATURE, cchData e o retorno da função ainda são contagens de TCHAR. A contagem é diferente para as versões ANSI e Unicode da função. Quando um aplicativo chama a versão genérica de GetLocaleInfo com LOCALE_FONTSIGNATURE, cchData pode ser especificado com segurança como sizeof(LOCALESIGNATURE) / sizeof(TCHAR).

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 = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                    (LPTSTR)&value,
                    sizeof(value) / sizeof(TCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_FONTSIGNATURE,
                    (LPWSTR)&LocSig,
                    sizeof(LocSig) / sizeof(TCHAR) );

A cadeia de caracteres ANSI recuperada pela versão ANSI dessa função é convertida de Unicode para ANSI com base na página de código ANSI padrão para o identificador de localidade. No entanto, se LOCALE_USE_CP_ACP for especificado, a tradução será baseada na página de código ANSI padrão do sistema.

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 (?).

Observação

O cabeçalho winnls.h define GetLocaleInfo como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

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	winnls.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll