Função GetUILanguageInfo (winnls.h)

Artigo
03/09/2024

Recupera uma variedade de informações sobre uma linguagem de interface do usuário instalada:

O idioma está instalado?
O usuário atual está licenciado para usar o idioma?
O idioma está totalmente localizado? Parcialmente localizado? Parte de um LIP (Pacote de Instalação de Idiomas)?
Se ele estiver parcialmente localizado ou parte de um LIP:
- Qual é a linguagem de fallback?
- Se esse idioma de fallback for um idioma parcialmente localizado, qual é sua base?
- Qual é o idioma de fallback padrão?

Sintaxe

BOOL GetUILanguageInfo(
  [in]                DWORD    dwFlags,
  [in]                PCZZWSTR pwmszLanguage,
  [out, optional]     PZZWSTR  pwszFallbackLanguages,
  [in, out, optional] PDWORD   pcchFallbackLanguages,
  [out]               PDWORD   pAttributes
);

Parâmetros

[in] dwFlags

Sinalizadores que definem o formato do idioma especificado. Os sinalizadores são mutuamente exclusivos e o padrão é MUI_LANGUAGE_NAME.

Valor	Significado
MUI_LANGUAGE_ID	Recupere as cadeias de caracteres de idioma no formato de identificador de idioma .
MUI_LANGUAGE_NAME	Recupere as cadeias de caracteres de idioma no formato de nome de idioma .

[in] pwmszLanguage

Ponteiro para idiomas para os quais a função deve recuperar informações. Esse parâmetro indica uma lista ordenada e delimitada por nulo de identificadores de idioma ou nomes de idioma, dependendo da configuração do sinalizador. Para obter informações sobre o uso desse parâmetro, consulte a seção Comentários.

[out, optional] pwszFallbackLanguages

Ponteiro para um buffer no qual essa função recupera uma lista ordenada e delimitada por nulo de linguagens de fallback, formatada conforme definido pela configuração de dwFlags. Essa lista termina com dois caracteres nulos.

Como alternativa, se esse parâmetro for definido como NULL e pcchLanguagesBuffer estiver definido como 0, a função recuperará o tamanho necessário do buffer de idioma em pcchLanguagesBuffer. O tamanho necessário inclui os dois caracteres nulos.

[in, out, optional] pcchFallbackLanguages

Ponteiro para o tamanho, em caracteres, para o buffer de idioma indicado por pwszFallbackLanguages. No retorno bem-sucedido da função, o parâmetro contém o tamanho do buffer de idioma recuperado.

Como alternativa, se esse parâmetro for definido como 0 e pwszLanguagesBuffer estiver definido como NULL, a função recuperará o tamanho necessário do buffer de idioma em pcchLanguagesBuffer.

[out] pAttributes

Ponteiro para sinalizadores que indicam atributos da lista de idiomas de entrada. A função sempre recupera o sinalizador que caracteriza o último idioma listado.

Valor	Significado
MUI_FULL_LANGUAGE	O idioma está totalmente localizado.
MUI_PARTIAL_LANGUAGE	O idioma é parcialmente localizado.
MUI_LIP_LANGUAGE	O idioma é uma linguagem LIP.

Além disso, pdwAttributes inclui um ou ambos os sinalizadores a seguir, conforme apropriado.

Valor	Significado
MUI_LANGUAGE_INSTALLED	O idioma está instalado neste computador.
MUI_LANGUAGE_LICENSED	O idioma é licenciado adequadamente para o usuário atual.

Retornar valor

Retornará TRUE se tiver êxito ou FALSE caso contrário. Para obter informações de erro estendidas, o aplicativo pode chamar GetLastError, que pode retornar os 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_PARAMETER. Qualquer um dos valores de parâmetro era inválido. Para obter mais informações, consulte Comentários.
ERROR_OBJECT_NAME_NOT_FOUND. O nome do objeto especificado não foi encontrado ou não era válido ou o primeiro idioma na lista de entrada não é um idioma instalado. Para obter mais informações, consulte Comentários.

Se GetLastError retornar qualquer outro código de erro, os parâmetros pcchFallbackLanguages e pdwAttributes serão indefinidos.

Comentários

MUI_LANGUAGE_NAME é recomendado em MUI_LANGUAGE_ID porque permite que a função faça um trabalho melhor de tratamento de linguagens LIP que não correspondem a localidades predefinidas, mas correspondem a uma localidade complementar. Idiomas LIP que correspondem a localidades predefinidas são tratados como idiomas não LIP.

Se o sinalizador MUI_LANGUAGE_ID for especificado, as cadeias de caracteres de idioma fornecidas deverão

use identificadores de linguagem hexadecimal que não incluem o 0x à esquerda e têm 4 caracteres de comprimento.

Por exemplo, en-US deve ser passado como "0409" e en como "0009". As cadeias de caracteres de idioma retornadas estarão no

mesmo formato.

Quando MUI_LANGUAGE_ID é especificado e, se houver esse idioma na lista de idiomas de interface do usuário preferenciais do usuário, poderá haver apenas um desses idiomas na lista. Essa linguagem pode ser especificada em pwmszLanguage como "1400", que corresponde ao valor hexadecimal de LOCALE_CUSTOM_UI_DEFAULT. Nenhuma outra linguagem desse tipo pode ser especificada usando MUI_LANGUAGE_ID. Usar "1000", que corresponde ao valor hexadecimal de LOCALE_CUSTOM_UNSPECIFIED, na cadeia de caracteres indicada por pwmszLanguage resultará em um código ERROR_INVALID_PARAMETER.

Um idioma parcialmente localizado pode ter um idioma de fallback parcialmente localizado, exigindo chamadas repetidas para GetUILanguageInfo para obter informações completas. Considere o caso de um idioma parcialmente localizado Lang1 que oferece uma opção de três idiomas de fallback. O idioma de fallback do Lang3 é parcialmente localizado e oferece uma opção de dois idiomas de fallback. As dependências são as seguintes, com o fallback padrão listado primeiro:

Lang1
- Lang2
- Lang3
  - Lang5
  - Lang6
- Lang4

Para obter as linguagens de fallback de Lang1, o aplicativo passa pwmszLanguage como "Lang1\0\0". No retorno da função, pwszFallbackLanguages é definido como "Lang2\0Lang3\0Lang4\0\0". Observe que a ordenação dessa lista indica que Lang2 é o idioma de fallback padrão.

Para obter as linguagens de fallback de Lang3 em relação a Lang1, o aplicativo passa pwmszLanguage como "lang1\0\lang3\0\0". No retorno da função, pwszFallbackLanguages é definido como "Lang5\0Lang6\0\0".

Essa função retorna ERROR_INVALID_PARAMETER para qualquer um dos seguintes:

pwmszLanguage é NULL ou vazio.
As MUI_LANGUAGE_ID e as MUI_LANGUAGE_NAME estão definidas.
Todos os sinalizadores que não sejam MUI_LANGUAGE_ID ou MUI_LANGUAGE_NAME são definidos.
pcchFallbackLanguages é maior que 0, mas pwszFallbackLanguages é NULL.
pwmszLanguage não pode ser analisado como um buffer de várias cadeias de caracteres de identificadores de idioma ou nomes de idioma, dependendo da configuração do sinalizador.

O código de erro ERROR_OBJECT_NAME_NOT_FOUND ocorrerá se pwmszLanguage puder ser analisado, mas não for válido. O código também pode ser retornado para um identificador de localidade inválido ou se o primeiro idioma na lista de entrada não for um idioma instalado ou se um idioma totalmente localizado tiver definido um idioma de fallback.

Assinatura do C#

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean GetUILanguageInfo(
            System.UInt32 dwFlags,
            System.String pwmszLanguage,
            System.IntPtr pwszFallbackLanguages,
            ref System.UInt32 pcchFallbackLanguages,
            ref System.UInt32 pdwAttributes
            );

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [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

Enumuilanguages

GetFileMUIInfo

Interface do Usuário Multilíngue

Funções de interface do usuário multilíngue

Compartilhar via

Função GetUILanguageInfo (winnls.h)

Sintaxe

Parâmetros

Retornar valor

Comentários

Assinatura do C#

Requisitos

Confira também

Comentários

Recursos adicionais