Função GetLocaleInfoA (winnls.h)

Artigo
11/20/2024

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

Observação Por motivos de interoperabilidade, o aplicativo deve preferir a função GetLocaleInfoExGetLocaleInfo 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.

Observação Para compatibilidade global, o aplicativo deve preferir os formulários de API "W" Unicode aos formulários "A". GetLocaleInfoA limitará os dados de caractere 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

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

Observação 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 de retorno

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

Observações

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

Observação 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 do GetLocaleInfo com LOCALE_FONTSIGNATURE, cchData pode ser especificada 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 é traduzida 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 que são indefinidos na página de código do sistema aparecem na cadeia de caracteres como um ponto de interrogação (?).

Nota

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. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows 2000 Server [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	winnls.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

GetLocaleInfoEx

GetSystemDefaultLCID

GetUserDefaultLCID

de Suporte à Linguagem Nacional

funções de suporte à linguagem nacional

recuperação e configuração de informações de localidade

SetLocaleInfo

Compartilhar via